RESTful API

rest_api_design.md

I am designing a RESTful API that will be used by test execution software to keep metadata about the tests it executes. It needs to save some information about the test itself, as well as which hosts it runs the tests on. Besides that, before starting a new test, test execution software needs to check whether any of the hosts it intends to run this test on, are already in use by other tests. I came up with the following. I have 3 resources: Host, Test, TestRun. There is a many-to-one relation for Host-Test, one-to-one relation for Test-TestRun, many-to-many relation for Host-TestRun.

I create a Host to start with:

POST api/v1/host

Request:
{
    "ip_address": "192.168.0.1",
    "hostname": "dell-r630.domain.com"
}

Response:

{
    "id": 5,
    "ip_address": "192.168.0.1",
    "hostname": "dell-r630.domain.com",
    "test_runs": []
}

Host IP address and hostname are unique. Before creating a new host the client will have to make sure one does not exist already.

Then I create a Test:

POST api/v1/test

Request:
{
    "test_id": "foo-bar-baz",
    "summary": "Youtube test on Dell R630 (H264, FullHD)",
    "repositories": "http://repo.domain.com/2.9.1.repo,http://repo.domain.com/2.9.1-CENTOS.repo"
}

Response:
{
    "id": 3,
    "test_id": "foo-bar-baz",
    "summary": "Youtube test on Dell R630 (H264, FullHD)",
    "repositories": "http://repo.domain.com/2.9.1.repo,http://repo.domain.com/2.9.1-CENTOS.repo",
    "test_run": null
}

Here repositories is the list of RPM repository URLs that were used by test excecution software to set up the host for the test.

Then I start the test specifying which hosts I want it to run on:

POST api/v1/test/{id}/run

Request:
{
    "hosts": [1, 3, 4]
}

Response:
{
    "id": 3,
    "test": 3,
    "start_time": "2016-11-23T14:37:52.679719",
    "end_time": null,
    "result": "",
    "file_store_url": "",
    "hosts": [
        1,
        3,
        5
    ]
}

Here the response is actually a newly created TestRun resource.

When the test execution software finishes running the test it must also mark it finished it by sending an API call:

POST api/v1/test/{id}/finish

Request:
{
    "result": "666 simultaneous sessions"
}

Response:
{
    "id": 3,
    "test": 3,
    "start_time": "2016-11-23T14:37:52.679719",
    "end_time": "2016-11-23T14:41:28.419925",
    "result": "666 simultaneous sessions",
    "file_store_url": "ftp://test-results.domain.com/foo-bar-baz",
    "hosts": [
        1,
        3,
        5
    ]
}

This request modifies the corresponding TestRun resource. file_store_url here is generated automatically by the server based on test_id.

Before the test tooling software starts a test it must also check whether any of the hosts it intends to use are already in use by other tests. There is an API call for this:

GET api/v1/host/1/used-by

Response:
[
    {
        "id": 3,
        "test": 3,
        "start_time": "2016-11-23T13:37:52.679719Z",
        "end_time": null,
        "result": "",
        "file_store_url": "",
        "hosts": [
            1,
            3,
            5
        ]
    }
]

If the host is in use the response will be a non-empty list of TestRun objects. Obviously, the response will always contain only one object. If the host if not in use, the response is an empty list.