/changes/id/revisions/id/checks/ REST API

This page describes the check-related REST endpoints that are added by the @PLUGIN@ plugin.

Please also take note of the general information on the REST API.

Check Endpoints

List Checks

‘GET /changes/{change-id}/revisions/{revision-id}/checks’

Retrieves all checks for a given revision and change.

Additional fields can be obtained by adding o parameters.

Request

  GET /changes/1/revisions/1/checks HTTP/1.0

As response a list of CheckInfo entities is returned. Returns checks for checkers regardless of their state (also for DISABLED checkers).

Response

  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: application/json; charset=UTF-8
  )]}'
  [
    {
      "repository": "test-repo",
      "change_number": 1,
      "patch_set_id": 1,
      "checker_uuid": "test:my-checker",
      "state": "NOT_STARTED",
      "url": "https://foo.corp.com/test-checker/results/123",
      "created": "2019-01-31 09:59:32.126000000"
      "updated": "2019-01-31 09:59:32.126000000"
    },
    {
      "repository": "test-repo",
      "change_number": 1,
      "patch_set_id": 1,
      "checker_uuid": "foo:foo-checker",
      "state": "FINISHED",
      "created": "2019-01-31 09:59:32.126000000"
      "updated": "2019-01-31 09:59:32.126000000"
    }
   ]

Get Check

‘GET /changes/{change-id}/revisions/{revision-id}/checks/{checker-id}

Retrieves a check.

Returns a check regardless of the state that the checker is in (also for DISABLED checkers).

Additional fields can be obtained by adding o parameters.

Request

  GET /changes/1/revisions/1/checks/test:my-checker HTTP/1.0

As response a CheckInfo entity is returned that describes the check.

Response

  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: application/json; charset=UTF-8
  )]}'
  {
    "repository": "test-repo",
    "change_number": 1,
    "patch_set_id": 1,
    "checker_uuid": "test:my-checker",
    "state": "NOT_STARTED",
    "url": "https://foo.corp.com/test-checker/results/123",
    "created": "2019-01-31 09:59:32.126000000"
    "updated": "2019-01-31 09:59:32.126000000"
  }

Create Check

‘POST /changes/1/revisions/1/checks/’

Creates a new check.

In the request body the data for the checker must be provided as a CheckInput entity.

Note that only users with the Administrate Checkers global capability are permitted to create check.

Request

  POST /changes/1/revisions/1/checks/ HTTP/1.0
  Content-Type: application/json; charset=UTF-8
  {
    "checker_uuid": "test:my-checker",
    "state": "RUNNING",
    "url": "https://foo.corp.com/test-checker/results/123",
    "started": "2019-01-31 09:59:32.126000000",
  }

As response the CheckInfo entity is returned that describes the created check.

Response

  HTTP/1.1 201 CREATED
  Content-Disposition: attachment
  Content-Type: application/json; charset=UTF-8
  )]}'
  {
    "repository": "test-repo",
    "change_number": 1,
    "patch_set_id": 1,
    "checker_uuid": "test:my-checker",
    "state": "RUNNING",
    "url": "https://foo.corp.com/test-checker/results/123",
    "started": "2019-01-31 09:59:32.126000000",
    "created": "2019-01-31 09:59:32.126000000"
    "updated": "2019-01-31 09:59:32.126000000"
  }

Update Check

‘POST /changes/1/revisions/1/checks/’

‘POST /changes/1/revisions/1/checks/test:my-checker’

Updates a check. The semantics are the same as for CreateCheck.

This REST endpoint supports partial updates of the checker property set. Only properties that are set in the CheckInput entity are updated. Properties that are not set in the input (or that have null as value) are not touched.

If the checker-id is provided as part of the URL, it must either match the value provided in the request body via CheckInput or the value in the request body is omitted.

Rerun Check

‘POST /changes/1/revisions/1/checks/test:my-checker/rerun’

Reruns a check. As response the CheckInfo entity is returned that describes the created check.

This REST endpoint supports rerunning a check. It also resets all relevant check fields such as message, url, started and finished.

JSON Entities

CheckInfo

The CheckInfo entity describes a check.

Field NameDescription
repositoryThe repository name that this check applies to.
change_numberThe change number that this check applies to.
patch_set_idThe patch set that this check applies to.
checker_uuidThe UUID of the checker that reported this check.
stateThe state as string-serialized form of CheckState
messageoptionalShort message explaining the check state.
urloptionalA fully-qualified URL pointing to the result of the check on the checker's infrastructure.
startedoptionalThe timestamp of when the check started processing.
finishedoptionalThe timestamp of when the check finished processing.
createdThe timestamp of when the check was created.
updatedThe timestamp of when the check was last updated.
checker_nameoptionalThe name of the checker that produced this check.
Only set if checker details are requested.
checker_statusoptionalThe status of the checker that produced this check.
Only set if checker details are requested.
blockingoptionalSet of blocking conditions that apply to this checker.
Only set if checker details are requested.
checker_descriptionoptionalThe description of the checker that reported this check.

CheckInput

The CheckInput entity contains information for creating or updating a check.

Field NameDescription
checker_uuidoptionalThe UUID of the checker. Must be specified for check creation. Optional only if updating a check and referencing the checker using the UUID in the URL.
stateoptionalThe state as string-serialized form of CheckState
messageoptionalShort message explaining the check state.
urloptionalA fully-qualified URL pointing to the result of the check on the checker's infrastructure.
startedoptionalThe timestamp of when the check started processing.
finishedoptionalThe timestamp of when the check finished processing.

CheckState (enum)

The CheckState enum can have the following values: NOT_STARTED, FAILED, SCHEDULED, RUNNING, SUCCESSFUL and NOT_RELEVANT.

Options

The following query options are supported in the o field of certain requests:

  • CHECKER: Include details from the configuration of the checker that produced this check.