debci API documentation

All requests to the API must provide a valid API key in the Auth-Key HTTP header. The only exception are the endpoints that manipulate the API keys themselves, in which case the requests must be authenticated using another method (HTTP basic authentication, client certificates, etc).

Example:

$ KEY='00000000-0000-0000-0000-000000000000'
$ curl --header "Auth-Key: $KEY" https://ci.debian.net/api/v1/auth

GET /v1/auth

This endpoint can be used to test your API key. It returns a 200 (OK) HTTP status if your API key is valid, and 403 (Forbidden) otherwise. The response also includes the username corresponding to the API key in the Auth-User header.

GET /v1/getkey

Displays a user-friendly HTML page that can be used by users to get an API key using this existing in-browser client certificate.

This endpoint does not require an existing API key, but does require proper authentication with a client certificate (e.g. Debian SSO).

POST /v1/getkey

Gets a new API key. Any existing API key is invalidated after a new one is obtained.

This endpoint does not require an existing API key, but does require proper authentication with a client certificate (e.g. Debian SSO)

GET /v1/retry/:run_id

Presents a simple UI for retrying a test

POST /v1/retry/:run_id

This endpoint can be used to reschedule a test that has already been performed, e.g. because the reason of the failure has been solved.

URL parameters:

GET /v1/test

Retrieves results for your test requests.

Parameters:

Some test results may be updated after being created, for example while a test is still running, it will be returned, but it's status will be null. After it is completed, it will be updated to have the correct status. So, if you are processing test results, make sure you support receiving the same result more than once, and updating the corresponding data on your side.

The response is a JSON object containing the following keys:

Note that this endpoint will only list requests that were made by the same API key that is being used to call it.

Example:

$ curl --header "Auth-Key: $KEY" https://ci.debian.net/api/v1/test?since=1508072999
{
  "until": 1508159423,
  "results": [
    {
      "trigger": "foo/1.2",
      "package": "bar",
      "arch": "amd64",
      "suite": "testing",
      "version": "4.5",
      "status": "fail",
      "run_id": 12345
    },
    {
      "trigger": "foo/1.2",
      "package": "baz",
      "arch": "amd64",
      "suite": "testing",
      "version": "2.7",
      "status": "pass",
      "run_id": 12346
    }
  ]
}

POST /v1/test/:suite/:arch

URL parameters:

Other parameters:

The tests JSON object must be an Array of objects. Each object represents a single test request, and can contain the following keys:

Note: each suite can be only present once.

In the example below, we are requesting to test debci and vagrant from testing, but with all binaries that come from the ruby-defaults source coming from unstable:

$ cat tests.json
[
  {
    "package": "debci",
    "trigger": "ruby/X.Y",
    "pin-packages": [
      ["src:ruby-defaults", "unstable"]
    ]
  },
  {
    "package": "vagrant",
    "trigger": "ruby/X.Y",
    "pin-packages": [
      ["src:ruby-defaults", "unstable"]
    ]
  }
]

# tests as a file upload
$ curl --header "Auth-Key: $KEY" --form tests=@tests.json           https://ci.debian.net/api/v1/test/testing/amd64

# tests as a regular POST parameter
$ curl --header "Auth-Key: $KEY" --data="$(cat tests.json)"           https://ci.debian.net/api/v1/test/testing/amd64

POST /v1/test/:suite/:arch/:package

This is a shortcut to request a test run for a single package.

URL parameters:

Example:

$ curl --header "Auth-Key: $KEY" --data '' https://ci.debian.net/api/v1/test/unstable/amd64/debci