id/revisions/id/checks/ REST APIThis 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.
‘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.
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).
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 /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.
GET /changes/1/revisions/1/checks/test:my-checker HTTP/1.0
As response a CheckInfo entity is returned that describes the check.
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"
}
‘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.
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.
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"
}
‘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.
‘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.
The CheckInfo entity describes a check.
| Field Name | Description | |
|---|---|---|
repository | The repository name that this check applies to. | |
change_number | The change number that this check applies to. | |
patch_set_id | The patch set that this check applies to. | |
checker_uuid | The UUID of the checker that reported this check. | |
state | The state as string-serialized form of CheckState | |
message | optional | Short message explaining the check state. Size limit is 10k by default, configured via plugin.checks.messageSizeLimit. |
url | optional | A fully-qualified URL pointing to the result of the check on the checker's infrastructure. |
started | optional | The timestamp of when the check started processing. |
finished | optional | The timestamp of when the check finished processing. |
created | The timestamp of when the check was created. | |
updated | The timestamp of when the check was last updated. | |
checker_name | optional | The name of the checker that produced this check. Only set if checker details are requested. |
checker_status | optional | The status of the checker that produced this check. Only set if checker details are requested. |
blocking | optional | Set of blocking conditions that apply to this checker. Only set if checker details are requested. |
checker_description | optional | The description of the checker that reported this check. |
submit_impact | optional | The CheckSubmitImpactInfo that describes a check's impact on the submission of the change. Only set if checker details are requested. |
The CheckInput entity contains information for creating or updating a check.
| Field Name | Description | |
|---|---|---|
checker_uuid | optional | The 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. |
state | optional | The state as string-serialized form of CheckState |
message | optional | Short message explaining the check state. |
url | optional | A fully-qualified URL pointing to the result of the check on the checker's infrastructure. |
started | optional | The timestamp of when the check started processing. |
finished | optional | The timestamp of when the check finished processing. |
notify | optional | Notify 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_details | optional | Additional 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. |
The CheckSubmitImpactInfo entity describes a check's impact on the submission of the change.
| Field Name | Description | |
|---|---|---|
required | When set, that check blocks change submission until it's in appropriate non-blocking state. |
The RerunInput entity contains information for rerunning a check.
| Field Name | Description | |
|---|---|---|
notify | optional | Notify 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_details | optional | Additional 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. |
The CheckState enum can have the following values: NOT_STARTED, FAILED, SCHEDULED, RUNNING, SUCCESSFUL and NOT_RELEVANT.
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.