API v1
======

Blueprint dedicated to the main API. It is composed of three namespaces, *client*,
*stats* and *processed*.

New namespaces are easily plugable via the file: ``api/v1/__init__.py``.


Security model
--------------

First, an overview of the security model.

Clients needs to have an activated account and a token in order to submit
new stats and to query the API. New clients can be created with the
`dedicated command <command-line-interface.html#creating-a-client>`_.

The token must be submitted in the headers of the requests with the key
``X-API-KEY``, as explained below. It is not needed to submit an additional id,
tokens are unique.


OpenAPI Specification
---------------------

Specification also available at
`https://dashboard.monarc.lu/api/v1 <https://dashboard.monarc.lu/api/v1/>`_.

.. literalinclude:: swagger.json
  :language: JSON


Detailed examples with the API
------------------------------

Getting stats for a client
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

    $ curl -X GET "http://127.0.0.1:5000/api/v1/stats" -H  "accept: application/json" -H  "X-API-KEY: rddPRk9_t-Z4GOgmY2UL2blKB1DxWB_0yhDlqcsF9p63eXs-oLCdm2c9YgP7cOqGz71GK1tc8lrCenD8AvEr-g"
    {
      "metadata": {
        "count": "0",
        "offset": "0",
        "limit": "0"
      },
      "data": []
    }

Specify a type of stats:

.. code-block:: bash

    $ curl --location --request GET \
    -H 'X-API-KEY: rddPRk9_t-Z4GOgmY2UL2blKB1DxWB_0yhDlqcsF9p63eXs-oLCdm2c9YgP7cOqGz71GK1tc8lrCenD8AvEr-g' \
    -H "Content-type: application/json" \
    -H "Accept: application/json" \
    -d '{"type":"threat"}' \
    'http://127.0.0.1:5000/api/v1/stats'



Invoking a processor
~~~~~~~~~~~~~~~~~~~~

Processors are utilities to process stats data. Processors are currently defined in
``statsservice/lib/processors.py``. They operate on different kind of stats:

- risks;
- threats;
- vulnerabilities.

They can do a lot of things, like evaluate different averages based on user
requirements. The result of the processor is sent in the response from the API.

You can get the list of available processors:

.. code-block:: bash

    $ curl http://127.0.0.1:5000/api/v1/stats/processed/list
    [
        {
            "name": "risk_averages",
            "description": "Evaluates the averages for the risks. Averages are evaluated per categories\n    (current/residual, informational/operational, low/medium/high)."
        },
        {
            "name": "risk_averages_on_date",
            "description": "Evaluates the averages for the risks per date. Averages are evaluated per categories\n    (current/residual, informational/operational, low/medium/high).\n    Supported parameters:\n    - risks_type: informational or operational\n    - risks_state: current or residual."
        },
        {
            "name": "threat_average_on_date",
            "description": "Aggregation and average of threats per date for each threat (accross all risk\n    analysis).\n    "
        },
        {
            "name": "vulnerability_average_on_date",
            "description": "Aggregation and average of vulnerabilities per date for each vulnerability\n    (accross all risk analysis).\n    "
        }
    ]


Some processors can use dedicated parameters. For this purpose the parameter
``processor_params`` can be used to transfer these parameters directly to the concerned
processor. These parameters will affect the behaviour of the processor.

For example you might want to call the processor ``risk_averages_on_date`` but you want
that this processor only evaluates the averages for *residual risks* that are also
*operational risks* (and not informational risks). The request will look like:

.. code-block:: bash

    curl -X GET "http://127.0.0.1:5000/api/v1/stats/processed/" -H  "accept: application/json" -H  "Content-Type: application/json" -d "{  \"type\": \"risk\",  \"processor\": \"risk_averages_on_date\",  \"local_stats_only\": 0, \"date_from\":\"2020-06-12\",\"processor_params\": {\"risks_type\":\"operational\",\"risks_state\":\"residual\"}}"


Internally the processor ``processor_params`` will honor the value provided with
the parameters ``risks_type`` and ``risks_state``.

- ``risks_type`` can be *informational* or *operational*;
- ``risks_state`` can be *current* or *residual*.


Generally, you can get information about a processor:


.. code-block:: bash

    $ echo -e `curl -s http://127.0.0.1:5000/api/v1/stats/processed/list | jq '.[] | select(.name=="risk_averages_on_date") | .description'`
    "Evaluates the averages for the risks per date. Averages are evaluated per categories
     (current/residual, informational/operational, low/medium/high).
     Supported parameters:
     - risks_type: informational or operational
     - risks_state: current or residual."