/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.

Notification options may be specified as RerunInput entity in the request body.

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. Size limit is 10k by default, configured via plugin.checks.messageSizeLimit.
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.
submit_impactoptionalThe CheckSubmitImpactInfo that describes a check's impact on the submission of the change.
Only set if checker details are requested.

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.
notifyoptionalNotify handling that defines to whom email notifications should be sent when the combined check state changes due to posting this check. Allowed values are NONE, OWNER, OWNER_REVIEWERS and ALL. If not set, the default is ALL if the combined check state is updated to either SUCCESSFUL or NOT_RELEVANT, otherwise the default is OWNER. Regardless of this setting there are no email notifications for posting checks on non-current patch sets.
notify_detailsoptionalAdditional information about whom to notify when the combined check state changes due to posting this check as a map of recipient type to NotifyInfo entity. Regardless of this setting there are no email notifications for posting checks on non-current patch sets.

CheckSubmitImpactInfo

The CheckSubmitImpactInfo entity describes a check's impact on the submission of the change.

Field NameDescription
requiredWhen set, that check blocks change submission until it's in appropriate non-blocking state.

RerunInput

The RerunInput entity contains information for rerunning a check.

Field NameDescription
notifyoptionalNotify handling that defines to whom email notifications should be sent when the combined check state changes due to rerunning this check. Allowed values are NONE, OWNER, OWNER_REVIEWERS and ALL. If not set, the default is OWNER. Regardless of this setting there are no email notifications for rerunning checks on non-current patch sets.
notify_detailsoptionalAdditional information about whom to notify when the combined check state changes due to rerunning this check as a map of recipient type to NotifyInfo entity. Regardless of this setting there are no email notifications for rerunning checks on non-current patch sets.

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.