Skip to main content

QA-Board's API

CLI API​

If you run batches, it can be useful to know where results where saved.

qa batch my-batch --list-output-dirs
##=> prints to STDOUT each output directory on a line
#> $some/where/place
#> $some/other/place
#> ...

qa batch my-batch --list
##=> prints to STDOUT an array with info on each run
# [
#   {
#      "absolute_input_path": "some/file"
#      "configurations": ["my-config"],
#      "output_directory": "some/place"
#   }
# ]

For specific needs, you can also use qa get to output internal variables:

qa get --input my/input output_dir
qa get commit_id
# etc

HTTP API​

TODO: Formalize with an openapi/swagger spec.

It's not documented yet, but quite stable and there are no surprises.

base_url=http://localhost:5151/api/v1
curl "$base_url/commits?project=group/my-project" | jq

To compare a commit's results with a reference, with the numbers of the Summary and Metrics Diff views, use /commit/<sha>/compare (experimental, see Quality gate).

Authentication​

Reading data doesn't need to be logged-in (unless the server blocks anonymous users). Some actions do, e.g. starting tuning runs. From scripts, use an API token: create one with a POST to /api/v1/user/token/ while logged-in, then send it with an Authorization: Bearer header, or as a ?token= URL parameter:

curl -H "Authorization: Bearer $QA_TOKEN" "$base_url/user/me/"
curl "$base_url/user/me/?token=$QA_TOKEN"

The qa CLI sends QA_TOKEN automatically, from the environment or from ~/.qaboard/secrets.yaml (see Client Installation). Tokens don't expire, so keep them private.

[
  // --snip--
  {
    "id": "af9370b9246657e74e8e7fbd28c180b5cca7d3a7",
    "type": "git",
    "branch": "origin/HM1_develop",
    "parents": [
      "c976adc9020683f90d51d25c39d9e177c621dc95"
    ],
    "message": "add dynamic min subtract\n",
    "committer_name": "Jane Doe",
    "committer_avatar_url": "https://gitlab.example.com/uploads/-/system/user/avatar/164/avatar.png",
    "authored_datetime": "2019-04-30T09:05:09+00:00",
    "authored_date": "2019-04-30",
    "data": null,
    "artifacts_url": "/s/mnt/qaboard/group/my-project/af/9370b9246657e7",
    "repo_artifacts_url": "/s/mnt/qaboard/group/my-project/af/9370b9246657e7",
    "batches": {
      "default": {
        "id": 19172,
        "commit_id": "af9370b9246657e74e8e7fbd28c180b5cca7d3a7",
        "label": "default",
        "created_date": "2019-04-30T09:08:59.962664",
        "data": {
          "type": "ci"
        },
        "batch_dir_url": "/s/mnt/qaboard/group/my-project/af/9370b9246657e7/output",
        "aggregated_metrics": {},
        "valid_outputs": 0,
        "pending_outputs": 0,
        "running_outputs": 0,
        "failed_outputs": 2
      }
    },
    "time_of_last_batch": "2019-04-30T09:05:09+00:00"
  },
  // --snip--
]

Lists of commits, branches and projects​

/commits gives the commits with results, newest first: by default those of the last days with commits, or of ?from=&to= (dates). Use /commits/<branch> for a branch's, ?committer=<name> for a committer's. It accepts:

  • ?limit= (at most 1000) and ?offset=, to get pages. The X-Has-More response header (true or false) tells if there are more.
  • ?q= to search all the project's commits, with the syntax of the web app's search box, e.g. q=branch:release -wip. Searches ignore the date range, unless you give from or to.

Without limit, it answers with at most 1000 commits, and no X-Has-More header.

curl -i "$base_url/commits?project=group/my-project&q=committer:alice&limit=50&offset=50"

/project/branches?project=group/my-project lists all the branches with results, by name. With &q=feature (branches whose name contains it) or &limit= (default 50, at most 1000), you get the most recently active branches first.

/projects gives the projects with results that you can access, with their data. With ?summary=true, it only gives what lists of projects need (git info, qaboard.yaml's project section): it's much smaller. Use /project?project=group/my-project for the rest.

curl "$base_url/commit/2032a39564281de429e667260d1def3d16980e01?project=group/my-project" | jq
{
  "id": "2032a39564281de429e667260d1def3d16980e01",
  "type": "git",
  "branch": "origin/InvestigateCompressionGW1",
  "parents": [
    "93b0a95d0ceaa78d24be33bea67a4aa333491c23"
  ],
  "message": "1. PARAMETERIZE compression\n2. add gw1 package\n",
  "committer_name": "Jane Doe",
  "committer_avatar_url": "https://gitlab.example.com/uploads/-/system/user/avatar/164/avatar.png",
  "authored_datetime": "2019-04-28T12:55:51+00:00",
  "authored_date": "2019-04-28",
  "data": {
    "qatools_config": {
      // --snip
     },
    "qatools_metrics": {
      // --snip
     }
  }
  "artifacts_url": "/s/mnt/qaboard/group/my-project/20/32a39564281de4",
  "repo_artifacts_url": "/s/mnt/qaboard/group/my-project/20/32a39564281de4",
  "batches": {
    "default": {
      "id": 19071,
      "commit_id": "2032a39564281de429e667260d1def3d16980e01",
      "label": "default",
      "created_date": "2019-04-28T13:27:28.119816",
      "data": {
        "type": "ci"
      },
      "batch_dir_url": "/s/mnt/qaboard/group/my-project/20/32a39564281de4/output",
      "aggregated_metrics": {},
      "valid_outputs": 1,
      "pending_outputs": 2,
      "running_outputs": 1,
      "failed_outputs": 2,
      "outputs": {
        "350582": {
          "id": 350582,
          "output_type": "",
          "platform": "windows",
          "configuration": "base_2X5",
          "extra_parameters": {},
          "metrics": {
            "is_failed": false,
            "compute_time": 30.1366302967
            "OTP_size_CrossTalk": 1040,
            "OTP_size_DayLight50": 464,
            // --snip
          },
          "is_failed": false,
          "is_pending": false,
          "is_running": false,
          "data": {
            "ci": true
          },
          "batch_dir_url": "/s/mnt/qaboard/group/my-project/20/32a39564281de4/output/windows/base-2x5/Truly_LSC_DB/M01",
          "test_input_database": "\\\\server\\QA-Data\\2X5",
          "test_input_path": "Truly_LSC_DB\\M01",
          "test_input_tags": []
        },
        // --snip--
      }
    }
  },
  "time_of_last_batch": "2019-04-28T12:55:51+00:00"
}