Web API (Cuirass Reference Manual)

7 Web API

The Cuirass web API is inspired from the Hydra one.

7.1 API description

7.1.1 Evaluation information

Single evaluation

It is possible to query the Cuirass web server for evaluation information. The dedicated API is "/api/evaluation?id=eval-id" where eval-id is the unique id associated to the evaluation in database.

For instance, querying a local Cuirass web server can be done with curl and jq to format the JSON response :

$ curl -s "http://localhost:8080/api/evaluation?id=1" | jq

{
  "id": 1,
  "specification": "guix-master",
  "status": 0,
  "timestamp": 1615289011,
  "checkouttime": 1615289011,
  "evaltime": 1615289655,
  "checkouts": [
    {
      "commit": "bd311f5a6ccbd4696ac77f0426a036bb375a2f10",
      "channel": "guix",
      "directory": "/gnu/store/6978xw9vs4ybg2pc3g736p1dba2056yl-guix-bd311f5"
    }
  ]
}

The nominal output is a JSON object whose fields are described hereafter.

id

The unique build id.

specification

The associated specification name, as a string.

status

The evaluation status, as an integer. Possible values are :

-1 -> started
0 -> succeeded
1 -> failed
2 -> aborted

checkouttime

The timestamp after channel checkout.

evaltime

The timestamp after evaluation completion.

checkouts

The evaluation checkouts as a JSON object.

Multiple evaluations

The latest evaluations list can be obtained with the API "/api/evaluations". The output is a JSON array of evaluations. Evaluations are represented as in the "/api/evaluation?id=eval-id" API.

This request accepts a mandatory parameter and an optional one.

nr: Limit query result to nr elements. This parameter is mandatory.
spec: Only consider evaluations that are part of the given spec specification.

7.1.2 Build information

It is possible to query Cuirass web server for build informations. The dedicated API is "/build/build-id" where build-id is the unique id associated to the build in database.

The build information can also be queried by output. For example, ‘/output/kg9mirg6xbvzcp0a98v7326n1nvvwgsj-hello-2.10’ will return the details of the output, along with the build if available.

$ curl -s "http://localhost:8080/build/2" | jq

{
  "id": 2,
  "jobset": "guix",
  "job": "acpica-20150410-job",
  "timestamp": 1501347493,
  "starttime": 1501347493,
  "stoptime": 1501347493,
  "buildoutputs": {
    "out": {
      "path": "/gnu/store/6g3njhfzqpdm335s7qhvmwvs5l7gcbq1-acpica-20150410"
    }
  },
  "system": "x86_64-linux",
  "nixname": "acpica-20150410",
  "buildstatus": 0,
  "weather": 0,
  "busy": 0,
  "priority": 0,
  "finished": 1,
  "buildproducts": null
}

If requested build-id is not known, the HTTP code 404 is answered with a JSON error message. For example:

$ curl -s "http://localhost:8080/build/fff"

{"error" : "Build with ID fff doesn't exist."}

The nominal output is a JSON object whose fields are described hereafter.

id

The unique build id.

jobset

The associated specification name, as a string.

job

The associated job-name, as a string.

timestamp

Timestamp taken at build creation time.

starttime

Timestamp taken at build start time.

stoptime

Timestamp taken at build stop time.

buildoutputs

Build outputs as a JSON object. The keys names are referring to the eventual output names. The associated value is another JSON object which only key is path. path value is the output directory in store as a string.

system

System name of the build, as a string.

nixname

Derivation name, as a string.

buildstatus

Build status, as an integer. Possible values are :

0 -> succeeded
1 -> failed
2 -> failed dependency
3 -> failed other
4 -> cancelled

weather

Build weather, as an integer.

-1 -> unknown
0 -> new-success
1 -> new-failure
2 -> still-succeeding
3 -> still-failing

busy

Whether the build is pending, as an integer.

priority

Build priority, as an integer.

finished

Build finished, as an integer.

buildproducts

Build products in store as a JSON object.

7.1.3 Build raw log output

It is possible to ask Cuirass for the raw build output log with the API "/build/build-id/log/raw" where build-id is the unique id associated to the build in database.

The output is a raw text, for example:

$ curl http://localhost:8080/build/2/log/raw

starting phase `set-SOURCE-DATE-EPOCH'
phase `set-SOURCE-DATE-EPOCH' succeeded after 0.0 seconds
starting phase `set-paths'
...

If requested build-id is not known, the HTTP code 404 is answered with a JSON error message. For example:

$ curl -s "http://localhost:8080/build/fff/log/raw"

{"error" : "Build with ID fff doesn't exist."}

7.1.4 Jobs

The list of jobs associated with a given evaluation can be obtained with the API "/api/jobs". The output is a JSON array of jobs.

This request accepts a mandatory parameter and multiple optional ones.

evaluation: The evaluation id. This parameter is mandatory.
names: Filter query result to jobs which names are part of the given names list, a comma separated list of job names.
system: Filter query result to jobs with the given system.

For example, to ask for the jobs of evaluation 12 for x86_64-linux:

$ curl "http://localhost:8080/api/jobs?evaluation=12&system=x86_64-linux"

or the emacs and emacs-minimal jobs of evaluation 12 for x86_64-linux:

$ curl "http://localhost:8080/api/jobs?evaluation=12&names=emacs.x86_64-linux,emacs-minimal.x86_64-linux"

The nominal output is a JSON object whose fields are described hereafter.

build: The unique build id associated with the job.
status: The build status, as an integer.
name: The job name, as a string.

7.1.5 Jobs history

The history of jobs across the last evaluations of a given specification can be optained with the API "/api/jobs/history".

This request accepts three mandatory parameters.

specification: The specification name. This parameter is mandatory.
names: Filter query result to jobs which names are part of the given names list, a comma separated list of job names. This parameter is mandatory.
nr: Limit query result to nr elements. This parameter is mandatory.

For example, to ask for the history of emacs.x86_64-linux and emacs-minimal.x86_64-linux jobs of the master specification over the last 10 evaluations:

$ curl "http://localhost:8080/api/jobs/history?spec=master&names=emacs.x86_64-linux,emacs-minimal.x86_64-linux&nr=10"

The nominal output is a JSON array which objects have the following field:

evaluation: The unique evaluation id.
checkouts: The evaluation checkouts as a JSON array.
name: The jobs list for this evaluation, as a JSON array.

7.1.6 Dashboard registration

The user can register a dashboard using the "/api/dashboard/register" API. This request accepts two mandatory parameters.

specification: The specification name. This parameter is mandatory.
names: The dashboard jobs names, where names is a comma separated list of job names. This parameter is mandatory.

For example, to register a dashboard for the emacs.x86_64-linux and emacs-minimal.x86_64-linux jobs of the master specification:

$ curl "http://localhost:8080/api/dashboard/register?spec=master&names=emacs.x86_64-linux,emacs-minimal.x86_64-linux"

The nominal output is a JSON object which contains a unique field:

id: The registered dashboard id.

The dashboard is then accessible at the following address: http://localhost:8080/dashboard/<id>.

7.1.7 Latest builds

The list of latest builds can be obtained with the API "/api/latestbuilds". The output is a JSON array of builds. Builds are represented as in the "/build/build-id" API.

This request accepts a mandatory parameter and multiple optional ones.

nr: Limit query result to nr elements. This parameter is mandatory.
jobset: Filter query result to builds with the given jobset.
job: Filter query result to builds with the given job name.
system: Filter query result to builds with the given system.

For example, to ask for the ten last builds:

$ curl "http://localhost:8080/api/latestbuilds?nr=10"

or the five last builds where jobset “guix”:

$ curl "http://localhost:8080/api/latestbuilds?nr=5&jobset=guix"

If no builds matching given parameters are found, an empty JSON array is returned.

7.1.8 Queued builds

The list of queued builds can be obtained with the API "/api/queue". The output is a JSON array of builds. Builds are represented as in the "/build/build-id" API.

This request accepts a mandatory parameter.

nr: Limit query result to nr elements. This parameter is mandatory.