API Endpoints
=============

The dashboard exposes a RESTful API.

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

All endpoints support signed cookie based authentication.

Login
~~~~~

To login, send a POST request to

.. code-block:: text

    POST /api/v1/login

with the following data

.. code-block:: text

    {'username': <username>, 'password': <password>}

Returns ``204 No Content`` on success or ``403 Forbidden`` if the username or password was not found.
On success a signed cookie is set.

Logout
~~~~~~

Send a GET or POST request without parameters to

.. code-block:: text

    POST /api/v1/logout

Returns ``204 No Content`` on success or ``403 Forbidden`` is the user was not logged in.
On success the signed cookie is cleared.

Projects
--------

Create a Project
~~~~~~~~~~~~~~~~

To create a new project send a POST request to

.. code-block:: text

    POST /api/v1/project/<project>

``<project>`` must be a valid project name consisting of ``A-Z``, ``a-z``, ``0-9``, ``-`` and ``_``.

POST data:

.. code-block:: text

    {'alias': <optional human readable name>}

Returns ``204 No Content`` on success.

``<alias>`` is an optional human-readable name for the project.

List projects
~~~~~~~~~~~~~

To list all projects, send a GET request to

.. code-block:: text

    GET /api/v1/projects

Returns ``200 OK`` on success.

Response:

.. code-block:: text

    {"my_project": {"name": "my_project", "alias": "My Project", ...}, ...}

Delete a Project
~~~~~~~~~~~~~~~~

To delete a project and all associated reports, requirements and tokens, send a DELETE request to

.. code-block:: text

    DELETE /api/v1/project/<project>

Returns ``204 No Content`` on success.

Project Information
-------------------

To get project information about a visible project, send a GET request to

.. code-block:: text

    GET /api/v1/project/<project>

Response:

.. code-block:: text

    {
        "name": <project-name>,
        "alias": <project-alias>,
        "last-modified": <utc-timestamp>,
        "number_of_reports": <int or null>,
        "current_number_of_successes": <int or null>,
        "current_number_of_tests": <int or null>,
        "current_number_of_successfully_covered_requirements": <int or null>,
        "current_number_of_requirements": <int or null>
    }

On success ``200 OK`` is returned.
If the current user is not allowed to access the project, ``404 Not Found`` is returned.

Reports
-------

Upload a Report
~~~~~~~~~~~~~~~

To upload a test report to a project, send a POST request to

.. code-block:: text

    POST /api/v1/project/<project>/report[/token/<token>]

POST data:

.. code-block:: text

    {'filename': <report filename>,
     'type': <report type>,
     'contents': <file contents>}

The ``/token/<token>`` is optional. ``type`` can be ``null`` or ``'junit'``.

Returns ``204 No Content`` on success.
``409 Conflict`` is returned if the report already exists.

List Reports
~~~~~~~~~~~~

To list all test reports of a project, send a GET request to

.. code-block:: text

    GET /api/v1/project/<project>/reports

Returns ``200 OK`` on success.

Response:

.. code-block:: text

    {"reports":
        [{"id": "0b2c2e38-3b57-47c7-a868-4e4c209a029a",
          "title": "Test Report",
          [...]
         },
         [...]
        ]
    }

Export a Report
~~~~~~~~~~~~~~~

To export a test report, send a GET request to

.. code-block:: text

    GET /api/v1/project/<project>/report/<report-id>

Returns ``200 OK`` on success and ``400 Bad Request`` if ``report-id`` is not supplied.

Response:

.. code-block:: text

    {"id": "0b2c2e38-3b57-47c7-a868-4e4c209a029a",
     "title": "Test Report",
     "date": "2020-01-01 00:00:00",
     "start_time": "2020-01-01 00:00:00",
     "start_timestamp": 1577833200.0,
     "stop_time": "2020-01-01 00:00:00",
     "stop_timestamp": 1577833200.0,
     "duration": "",
     "seconds": 4503.94160399791,
     "test_amount": 1,
     "successes": 1,
     "errors": 0,
     "failures": 0,
     "skipped": 0,
     "unexpected_successes": 0,
     "expected_failures": 0,
     "metadata": "",
     "htf_version": "1.3.0",
     "python_version": "3.7",
     "license_information": "",
     "platform": "Linux-4.15.0-55-generic-x86_64-with-Ubuntu-18.04-bionic",
     "hostname": "test host",
     "machine": "x86_64",
     "tests": [{"result": "success",
                "data": {"links": []}
               }],
     "number_of_tested_requirements": 0,
     "number_of_successfully_tested_requirements": 0,
     "number_of_unsuccessfully_tested_requirements": 0,
     "tested_requirements": ["REQ-1", "REQ-2", "REQ-3"],
     "successfully_tested_requirements": ["REQ-1", "REQ-2"],
     "unsuccessfully_tested_requirements": ["REQ-3"]}


Delete a Report
~~~~~~~~~~~~~~~

To delete a test report from a project, send a DELETE request to

.. code-block:: text

    DELETE /api/v1/project/<project>/report/<report-id>

Returns ``204 No Content`` on success.

Requirements
------------

Upload Requirements
~~~~~~~~~~~~~~~~~~~

To upload requirements to a project, send a POST request to

.. code-block:: text

    POST /api/v1/project/<project>/requirements

POST data

.. code-block:: text

    {'filename': <requirements filename>,
     'type': <requirements type>,
     'contents': <file contents>,
     'date': <date>}

Date must be in strptime-format ``%Y-%m-%d %H:%M:%S``. ``type`` can be ``null`` or ``'csv'``.

Returns ``204 No Content`` on success.

List Uploaded Requirements
~~~~~~~~~~~~~~~~~~~~~~~~~~

To list uploaded requirements, send a GET request to

.. code-block:: text

    GET /api/v1/project/<project>/requirements

Returns ``200 OK`` on success.

Response:

.. code-block:: text

    [{"date": "2020-01-01 00:00:00",
      "requirements": ["REQ-1", "REQ-2", "REQ-3"],
      "number_of_requirements": 0,
      "id": "5f2a6479b5503fc71875a778"},
     [...]
    ]

Export Requirements
~~~~~~~~~~~~~~~~~~~

To export requirements, send a GET request to

.. code-block:: text

    GET /api/v1/project/<project>/requirements/<requirements-id>

Returns ``200 OK`` on success.

Response:

.. code-block:: text

    {"date": "2020-01-01 00:00:00",
     "requirements": ["REQ-1", "REQ-2", "REQ-3"],
     "number_of_requirements": 0,
     "id": "5f2a6479b5503fc71875a778"}


Delete Requirements
~~~~~~~~~~~~~~~~~~~

To delete requirements from a project, send a DELETE request to

.. code-block:: text

    DELETE /api/v1/project/<project>/requirements/<requirements-id>

Returns ``204 No Content`` on success.

Tokens
------

Create Token
~~~~~~~~~~~~

To create a new token for a project, send a POST request to

.. code-block:: text

    POST /api/v1/project/<project>/token

POST data:

.. code-block:: text

    {'name': <token identifier>}

Returns ``201 Created`` on success and response.

.. code-block:: text

    {'token': <token identifier>}

List Tokens
~~~~~~~~~~~

To list all tokens for a project, send a GET request to

.. code-block:: text

    GET /api/v1/project/<project>/tokens

Returns ``200 OK`` on success.

Response:

.. code-block:: text

    {
        "707bcd17ef364263848bf5e3ecfeb755f01e11fee492d9f6361d3c0d": "token_0",
        "4479723524bcb8a562e861cd8ef1998b431114ef4213e38b16dba026": "token_1",
        # ...
    }

Delete Token
~~~~~~~~~~~~

To delete a token from a project, send a DELETE request to

.. code-block:: text

    DELETE /api/v1/project/<project>/token/<token>

Returns ``204 No Content`` on success.

Cache
-----

Results that are shown in the user interface are cached.
A cache rebuild can be forced by sending a POST request to

.. code-block:: text

    POST /api/v1/project/<project>/cache

Returns ``204 No Content`` on success or ``404 Not Found`` if the project was not found.

User Management
---------------

Users and roles can be managed via the API.

List Users
~~~~~~~~~~

Send a GET request to

.. code-block:: text

    GET /api/v1/users

Returns ``200 OK`` on success with the payload

.. code-block:: text

    [
        {
            'username': <username>,
            'projects': {
                '<project-1>': {
                    'roles': ['manager', 'user'],
                },
                # ...
        },
        # ...
    ]

Add User
~~~~~~~~

To add a user, send a POST request to

.. code-block:: text

    POST /api/v1/user/<username>

with the payload

.. code-block:: text

    {'password': <password>}

Returns ``204 No Content`` on success or ``409 Conflict`` if the user already exists.

Requires user ``root``.

Delete User
~~~~~~~~~~~

To add a user, send a DELETE request to

.. code-block:: text

    DELETE /api/v1/user/<username>

Returns ``204 No Content`` on success, ``404 Not Found`` if the user does not
exist and ``403 Forbidden`` if the current user is not root or the supplied username
is ``root``. The user ``root`` cannot be removed.

Requires user ``root``.

Get User Information
~~~~~~~~~~~~~~~~~~~~

To get user information, send a GET request to

.. code-block:: text

    GET /api/v1/user
    GET /api/v1/user/<username>

.. code-block:: text

    {
        'username': <username>,
        'projects': {
            '<project-1>': {
                'roles': ['manager', 'user'],
            },
            # ...
    }

If no ``<username>`` is supplied, the current username is used.

Returns ``200 OK`` on success, ``404 Not Found`` if the user was not found and
``403 Forbidden`` if a user is not root or does not read its own information.

Requires user ``root`` to read user information for different users.

Change User's Password
~~~~~~~~~~~~~~~~~~~~~~

To change the user's password, send a PUT request to

.. code-block:: text

    PUT  /api/v1/user
    PUT  /api/v1/user/<username>

with payload

.. code-block:: text

    {'password': <password>}

If no ``<username>`` is supplied the current username is used.

Returns ``204 No Content`` on success, ``404 Not Found`` if the user does not exist and
``403 Forbidden`` if a user is not root and does not change its own password.

Requires user ``root`` to change password for other users.

Set User's Project Roles
~~~~~~~~~~~~~~~~~~~~~~~~

To set roles for projects, send a PUT request as root to

.. code-block:: text

    PUT /api/v1/user/<username>/roles

with payload

.. code-block:: text

    {
        <project-0>: [role-1, role-2, role-N],
        # ...
    }

Each role must be one out of ``"admin", "user"``. If you want to remove a user's role, leave the list of roles empty.

Returns ``204 No Content`` on success, ``404 Not Found`` if the user was not found and
``403 Forbidden`` if the current user is not root.

Projects don't have to exist. Thus roles can be created before a project is created.