ConDB2 REST API
===============


Getting data - <URL prefix>/get
-------------------------------

HTTP method: GET

Arguments
~~~~~~~~~

* **folder**: *text*, required - folder name. If the folder is in non-default namespace (schema), the folder name is in the format: <namespace>.<folder name>.
* **t**: *int* or *float* - Validity timestamp to get data for.
* **t0**, **t1**: *int* or *float* - Valitity time range to get data for. If t is specified, t0 and t1 are ignored.
* **data_type**: *text* - data type to get data for. If unspecified, the data will be returned regardless of the data types.
* **format**: *text*, optional - format of the output representation, ``csv`` or ``json``. Default: ``csv``

Example:

    .. code-block:: shell

        $ curl "http://host:8080/path/get?folder=my_schema.my_data&t=125436.0&format=json"

Adding data - <URL prefix>/put
------------------------------

HTTP method: POST
Authentication required

Arguments
~~~~~~~~~

* **folder**: *text*, required - folder name. If the folder is in non-default namespace (schema), the folder name is in the format: <namespace>.<folder name>.
* **tr**: *float*, *int* or *text* - the "record time" to associate the new data with. Default: current time.
* **data_type**: *text* - data type to associate the data with. Default - blank, "".

Request body must contain CSV-formatted data with first line containing list of columns in the CSV file. First 2 names must be the "channel" and "tv".
The rest must be a list of one or more data columns.

Example:

    .. code-block::

        channel,tv,x1,x2,y
        1,137,25.4,37.3,-3
        2,137,26.4,137.3,-2
        2,140,27.4,237.5,-2
        3,134,28.4,137.7,-1

The ``put`` method requires authentication. Currently, the only authentication implemented mechanism is ``digest authentication`` described in :rfc:`2617`.
This authentication mechanism is supported by `curl <https://curl.se/curl>`_ and by `requests <https://docs.python-requests.org/en/latest/index.html>`_ Python library. To use is with ``curl``:

    .. code-block:: shell

        $ curl -X POST -T data.csv --digest -u username:password http://.../put?folder=...

To use with ``requests`` library:

    .. code-block:: python

        import requests
        from requests.auth import HTTPDigestAuth

        response = requests.post(url, data, auth=HTTPDigestAuth(username, password))


Tagging database state - <URL prefix>/tag
-----------------------------------------

HTTP method: POST
Authentication required

Arguments
~~~~~~~~~

* **folder**: *text*, required - folder name. If the folder is in non-default namespace (schema), the folder name is in the format: <namespace>.<folder name>.
* **tr**: *float*, *int* or *text*, optional - the "record time" to associate the new data with. Default: current time.
* **copy_from**: *text*, optional - existing tag to make a copy. If ``copy_from`` is used, ``tr`` is ignored.
* **override**: *text*, "yes" or "no", optional - if "yes" and the tag with the same name exists, the tag will be moved to the new Tr. Default is "no"

The method requires ``digest authentication``, same as the ``put`` method.

Listing existing tags - <URL prefix>/tags
-----------------------------------------

HTTP method: GET

Arguments
~~~~~~~~~

* **folder**: *text*, required - folder name. If the folder is in non-default namespace (schema), the folder name is in the format: <namespace>.<folder name>.
* **format**: *text*, optional - format of the output representation, ``csv`` or ``json``. Default: "csv"

Listing existing data types - <URL prefix>/data_types
-----------------------------------------------------

HTTP method: GET

Arguments
~~~~~~~~~

* **folder**: *text*, required - folder name. If the folder is in non-default namespace (schema), the folder name is in the format: <namespace>.<folder name>.
* **format**: *text*, optional - format of the output representation, ``csv`` or ``json``. Default: ``csv``