REST API

In order to enable users and scripts to interface with SoTest deployments, a REST API provides access to different functionality.

Some functionality is only available to users that have logged in first.

Login

API endpoints that require authentication use the basic access authentication method.

This means that there are two ways to authenticate via tools like curl:

The following examples assume that “Aladdin” is the user name and “OpenSesame” is the password.

URL Authentication

Username and password can be encoded in the URL when calling an API endpoint:

curl https://Aladdin:OpenSesame@opensource.sotest.io/path/to/api/endpoint

netrc Authentication

SoTest login information can be stored in a netrc file. This file can either be stored in the user’s home folder as ~/.netrc or elsewhere. Refer to the curl documentation for more detailed information.

Examples:

# this call allows curl to lookup login information from ~/.netrc
curl --netrc https://opensource.sotest.io/path/to/api/endpoint

# this call provides a netrc file from elsewhere
curl --netrc-file /path/to/netrc-file \
  https://opensource.sotest.io/path/to/api/endpoint

The netrc file would contain the following content:

machine opensource.sotest.io
login Aladdin
password OpenSesame

/api/create - Create a Test Run

The POST endpoint for test run creation is /api/create and requires authentication. This endpoint assumes the following parameters:

Parameters

  • boot_files_url: The URL from which SoTest controllers can download the binaries that must be booted in order to execute the tests.
  • name: Display name of the test run in the web UI.
  • url: Display URL of the test run in the web UI. This might for example be the URL of a pull request that is tested.
  • config: The YAML/JSON encoded project configuration as file upload.
  • priority: Optional integer field that describes the priority of the test run. Higher number means higher priority. Priorities can be negative. Default priority is 0.

Return Value

If authentication and test run creation were successful, the server returns a HTTP 200 status code and emits just the ID of the new test run.

Example Call

curl --netrc \
     -F 'boot_files_url=https://my.artifacts.server/commit-123.zip' \
     -F 'url=https://github.com/my-org/my-project/pull/123' \
     -F 'name=Pull request #123' \
     -F 'config=@/path/to/project_config.yaml'
     https://opensource.sotest.io/api/create

/api/query/:id - Query the State of a Test Run

The GET endpoint for test run creation is /api/query/:id, where :id is the test run ID. This endpoint assumes no other parameters.

Return Value

In case the test run exists, this endpoint returns a HTTP 200 status code along with the following JSON document:

{"tag":"<TAG>"}

<TAG> is one of the following symbols:

  • UNFINISHED: Test run did not finish, yet.
  • SUCCESS: Test run finished without any test failures.
  • FAIL: Test run finished with one or more test failures.
  • DISABLED: Test run was disabled by user or general infrastructure failures.
  • ERROR: Unable to find testrun

Example Call

curl https://opensource.sotest.io/api/query/123