.. Author: Hossein Safavi

.. STATUS: draft

.. role:: red

################
REST APIs
################


There are three **REST** APIs available at Byteflies:

Public API
    The public API is meant to be used by researchers and external developers that need to fetch data from our systems.
    It is authenticated using an API token which is required for every API call in lieu of username/passwords (which
    are only required when fetching a token).

Device API
    This API is meant for data ingestion into the Byteflies cloud from the devices/boxes. At this moment, it includes
    functionality aimed at data uploading from the mac minis. It is currently **not authenticated**

UI API
    This **internal** API is meant to be used exclusively by our in-house UIs. There is special functionality that
    is optimized to reduce the number of API calls required to generate common UI views thereby reducing latency and
    time-to-first-draw.

**************
API References
**************
If you simply want to access the APIs at ``https://api.byteflies.be`` to fetch data, refer to the endpoint references:

:doc:`Public API<api-user>`
    Here is something


****************
Running the APIs
****************


.. danger::
    **DO NOT** run your test code against the real database. Make sure you run **local docker images**. I will hunt you
    down and make you listen to hours of Nickelback.

The APIs are all dockerized for easy deployment. However, when debugging, it is easier to run the non-dockerized
version. Both versions are included when you clone the repository so you do not have to anything special to fetch them.
Say you wish to fetch an API named ``bf-api``, simply clone the repository to a local folder:

.. code-block:: bash

    mkdir -p ~/repo && cd repo && git clone git@github.com:Byteflies/bf-api.git


Folder Structure
================

Each respository will have a different folder structure. However, the most important files and folders are organized as
follows:

.. code-block:: bash

    api-env
        logs/

        mysql/
            db_data/

            docker-compose.yml

        releases/

        src/
            nimbus/
            orm/
            resources/

            app.py
            wsgi.py
            api-env.ini
            config.py


        aws.env
        docker-compose-aws.yml
        docker-compose.yml
        Dockerfile
        requirements.txt

``logs``
    This folder is mounted within Docker images as the central place to store all log files (``flask`` and ``uWSGI``)
``mysql``
    This folder contains the ``docker-compose`` project that can be used to setup a test mysql server. The data needed
    to populate the ``db_data`` folder can be downloaded in binary format from the Byteflies file repository.
``src``
    The actual source files for the project are stored here (the flask project)
        ``app.py``
            This file is the flask application as well as a basic debug setup in case the built-in flask server is to be
            used. Running in this mode does not connect to Cassandra
        ``api-env.ini``
            This is the config file to ``uWSGI`` which included the needed parameters. Running using uWSGI will initiate
            the Cassandra connection
        ``config.py``
            Reads config variables from the environment if available and sets default values if needed
``aws.env``
    This env file is needed when deploying in an AWS VM using the ``docker-compose-aws.yml`` project

Dependencies & Installation
===========================

Refer to the ``requirements.txt`` file included in each repository to install the correct dependencies (for dev work),
otherwise, the only dependency is ``docker`` and ``docker-compose``.


Development Mode
----------------

Assume that you have cloned the API repository of interest into ``~/repo/bf-api/`` and that you have pre-made a folder
called ``~/venv/`` to store your python virtual environment. Then you can prepare your development environemnt by
running the following commands:

.. code-block:: bash

    virtualenv ~/venv/api-env
    source ~/venv/api-env/bin/activate
    pip install cython
    pip install numpy
    pip install -r ~/repo/bf-api/requirements.txt

.. attention::
    Make sure that ``cython`` and ``numpy`` are installed **before** ``cassandra-driver`` otherwise the driver will not be able
    to use the ``numpy-protocol-handler``. You can check if the installation was done correctly by running:

    .. code-block:: python

        from cassandra.cython_deps import HAVE_CYTHON, HAVE_NUMPY
        print HAVE_CYTHON, HAVE_NUMPY

    which should print out: ``True True``

VSCODE Settings
~~~~~~~~~~~~~~~
Make sure that you have already installed the Python extension for VSCODE. I also recommend the following extensions for
VSCODE:

1. Bracket Pair Colorizer
2. Docker

Then, inside your repository folder ``~/repo/bf-api/``, run the following commands:

.. code-block:: bash

    mkdir ~/repo/bf-api/.vscode
    touch ~/repo/bf-api/.vscode/settings.json

and place the following lines in the file ``settings.json``:

.. code-block:: javascript

    {
        "python.pythonPath": "/your/home/folder/venvapi-env/bin/python"
    }

If you are annoyed by some of the linting messages and you have set up linting, you can disable some by adjusting the
``settings.json`` file:

.. code-block:: javascript

    {
        "python.pythonPath": "/your/home/folder/venvapi-env/bin/python",
        "python.linting.pylintArgs": ["--disable=C0103,C0301,C0111,C1001,W0232"]
    }


From the Terminal
~~~~~~~~~~~~~~~~~
Outside of VSCODE, simply run:

.. code-block:: bash

    source ~/venv/api-env/bin/activate
    cd ~/repo/bf-api/src
    python app.py