.. Gencove REST API documentation master file, created by
   sphinx-quickstart on Fri Feb  3 11:09:26 2017.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Gencove REST API docs
=====================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

Summary
-------

.. endpoints to include need to be listed under 'qrefflask' (here) *AND* under 'autoflask' (below)

.. qrefflask:: seeqapp.webserver:app
  :endpoints: root, health, welcomeapikey, projects, project, projectstats, projectimagev2, projectsamples, projectsample, projectrawdata, projectsampleorder, projectsamplesorders, sample, sampleprojects, sampleproject
  :order: path

API Conventions
---------------

HTTP responses 
^^^^^^^^^^^^^^

A standard response from the Gencove backend will have 
``Content-Type: application/json``. It will also typically have a ``message`` 
field with straightforward feedback intended for the user and a 
``message_details`` field with more detailed information. Unless explicitly 
modified, this convention can be assumed for all classes of HTTP responses 
(2xx, 4xx, 5xx, etc.)

**Example response**:

.. sourcecode:: http

    HTTP/1.1 200 OK
    Content-Type: application/json

    {
        "message": "Message intended for user",
        "message_details": "More detailed message"
    }

In order to avoid denoting specific responses for these two fields, the 
documentation will display them as follows:

.. sourcecode:: http

    HTTP/1.1 200 OK
    Content-Type: application/json

    {
        "message": "...",
        "message_details": "..."
    }

Date and other
^^^^^^^^^^^^^^

In some cases, an API response contains a date field. This is an example of a 
date field:

.. sourcecode:: http

    HTTP/1.1 200 OK
    Content-Type: application/json

    {
        "created": {
            "year": 2017,
            "month": 2,
            "month_name": "February",
            "day": 6,
            "hour": 19,
            "minute": 30,
            "second": 36,
            "datetime_string": "February 06, 2017 at 7:30 PM",
            "date_string": "February 06, 2017",
            "time_string": "7:30 PM",
            "iso8601": "2017-02-06T19:30:36"
        }
    }

In order to declutter the documentation, date fields (and other irrelevant 
fields) will be shown as follows in order to maintain valid JSON formatting:

.. sourcecode:: http

    HTTP/1.1 200 OK
    Content-Type: application/json

    {
        "created": {
            "...": "..."
        }
    }

Endpoints
^^^^^^^^^

.. endpoints to include need to be listed under 'qrefflask' (above) *AND* under 'autoflask' (here)

.. autoflask:: seeqapp.webserver:app
  :endpoints: root, health, welcomeapikey, projects, project, projectstats, projectimagev2, projectsamples, projectsample, projectrawdata, projectsampleorder, projectsamplesorders, sample, sampleprojects, sampleproject
  :order: path


.. Indices and tables
.. ==================

.. * :ref:`genindex`
.. * :ref:`modindex`
.. * :ref:`search`