API Endpoints

The dashboard exposes a RESTful API.

Authentication

All endpoints support signed cookie based authentication.

Logout

Send a GET or POST request without parameters to

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

POST /api/v1/project/<project>

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

POST data:

{'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

GET /api/v1/projects

Returns 200 OK on success.

Response:

{"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

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

GET /api/v1/project/<project>

Response:

{
    "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

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

POST data:

{'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

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

Returns 200 OK on success.

Response:

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

Export a Report

To export a test report, send a GET request to

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

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

Response:

{"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

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

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

POST data

{'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

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

Returns 200 OK on success.

Response:

[{"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

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

Returns 200 OK on success.

Response:

{"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

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

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

POST data:

{'name': <token identifier>}

Returns 201 Created on success and response.

{'token': <token identifier>}

List Tokens

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

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

Returns 200 OK on success.

Response:

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

Delete Token

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

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

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

GET /api/v1/users

Returns 200 OK on success with the payload

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

Add User

To add a user, send a POST request to

POST /api/v1/user/<username>

with the payload

{'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

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

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

{
    '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

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

with payload

{'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

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

with payload

{
    <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.

API Endpoints

Authentication

Login

Logout

Projects

Create a Project

List projects

Delete a Project

Project Information

Reports

Upload a Report

List Reports

Export a Report

Delete a Report

Requirements

Upload Requirements

List Uploaded Requirements

Export Requirements

Delete Requirements

Tokens

Create Token

List Tokens

Delete Token

Cache

User Management

List Users

Add User

Delete User

Get User Information

Change User’s Password

Set User’s Project Roles