REST API
========

Information on how to access and control the Phenome Agent using the REST API. The API can return information about the Model, Objects, Properties, Collected KPIs, Predictions, perform operations, etc. Most everything that can be done with the Agent should be possible through the API.

Call Structure
-----------------

Standard API call structure is like this:

::

    GET /api/v1/{API_ENDPOINT}/{PARAMETERS}/{VERBOSE}/{REQUEST_ID} HTTP/1.1

There are some common parameters for most API calls.

- **VERBOSE** (int - 0 or 1). If set to 1 - tells the API to return a response with as much information as possible.
- **REQUEST_ID** (int - any number). Allows sending of a specific integer value to the API, which will be returned in the response.

Authentication
-----------------

Currently the agent API uses **HTTP Basic Authentication** for some "protected" calls - HTTPS can be used for additional security by simply modifying the run.py file to include a self-signed cert. The default username and password can be set in the local **phenome.ini** file.

Response Structure
------------------

All API Calls return the same structure

.. code-block:: json

  {
     "api_version": 1,
     "core_version": "1.0.0",
     "data": [],
     "error": "None",
     "request_id": "1",
     "status": 0
  }

- **api_version** is the version of the API
- **core_version** is the version of the agent responding
- **data** is a data structure that is unique to the endpoint / API call
- **error** textual description of any error that occured. 'None' is no error.
- **request_id** always returned in case caller needs to track original request ID (i.e. async processing)
- **status** a status code of 0 is

Endpoints
---------

.. autosummary::
   :toctree: generated

   phenome_core.core.api