| @PLUGIN@ - /changes/ REST API | |
| ============================== | |
| This page describes the '/changes/' REST endpoints that are added by | |
| the @PLUGIN@ plugin. | |
| Please also take note of the general information on the | |
| [REST API](../../../Documentation/rest-api.html). | |
| <a id="plugin-endpoints"> @PLUGIN@ Endpoints | |
| -------------------------------------------- | |
| ### <a id="get-verifications"> Get Verifications | |
| __GET__ /changes/{change-id}/revisions/{revision-id}/@PLUGIN@~verifications | |
| Gets the [verifications](#verification-info) for a change. Please refer to the | |
| general [changes rest api](../../../Documentation/rest-api-changes.html#get-review) | |
| for additional info on this request. | |
| #### Request | |
| ``` | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/@PLUGIN@~verifications HTTP/1.0 | |
| ``` | |
| #### Response | |
| ``` | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "5081c5e5-e101-43eb-8e59-4e197f22a0d0"": { | |
| "name": "gate-horizon-pep8", | |
| "url": "https://ci.host.com/jobs/gate-horizon-pep8/2711", | |
| "value": -1, | |
| "reporter": "Jenkins Check", | |
| "comment": "Failed", | |
| "category": "cloud server", | |
| "duration": "3m 10s" | |
| "granted": "15 Mar 2016 08:10:41", | |
| }, | |
| "2a359a73-31e7-4f81-b295-ae0e20615da6": { | |
| "name": "gate-horizon-python27", | |
| "url": "https://ci.host.com/jobs/gate-horizon-python27/1711", | |
| "value": 1, | |
| "abstain": true, | |
| "reporter": "Acme CI", | |
| "comment": "Informational only", | |
| "category": "third party", | |
| "duration": "7m 40s" | |
| "granted": "15 Mar 2016 08:30:16" | |
| } | |
| "807c8ece-0196-4ec4-b24f-ed035efa8e55": { | |
| "name": "gate-horizon-python34", | |
| "url": "https://ci.host.com/jobs/gate-horizon-python34/9111", | |
| "value": 1, | |
| "reporter": "Drone CI", | |
| "comment": "RuntimeError: File was not found", | |
| "granted": "15 Mar 2016 08:40:23", | |
| "category": "third party", | |
| "duration": "12m 20s" | |
| "granted": "15 Mar 2016 08:40:23", | |
| } | |
| } | |
| ``` | |
| ### <a id="verification-options"> Verification Options | |
| Verifications Options | |
| Sort(s):: | |
| Sort the results by a field. | |
| |Field Name |Description| | |
| |:----------|:----------| | |
| |NAME |Sort job name in ascending order| | |
| |REPORTER |Sort reporter in ascending order| | |
| *__Note__: Fields are also sorted by the time the job was saved in descending | |
| order. | |
| #### Request | |
| ``` | |
| GET /changes/100/revisions/1/@PLUGIN@~verifications/?sort=REPORTER HTTP/1.0 | |
| ``` | |
| Filter(f):: | |
| |Field Name |Description| | |
| |:----------|:----------| | |
| |CURRENT |Limit the results to the most current list of reports| | |
| |FAILED |Limit the results to only failed jobs| | |
| #### Example | |
| Assuming "Jenkins Check" and "ACME CI" published multiple reports to Gerrit. | |
| Retrieve the most current report(s) by each reporter: | |
| #### Request | |
| ``` | |
| GET /changes/100/revisions/1/@PLUGIN@~verifications/?sort=REPORTER&filter=CURRENT HTTP/1.0 | |
| ``` | |
| #### Response | |
| ``` | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "2a359a73-31e7-4f81-b295-ae0e20615da6": { | |
| "name": "gate-horizon-python27", | |
| "url": "https://ci.host.com/jobs/gate-horizon-python27/1711", | |
| "value": 1, | |
| "abstain": true, | |
| "reporter": "Acme CI", | |
| "comment": "Informational only", | |
| "category": "third party", | |
| "duration": "7m 40s" | |
| "granted": "15 Mar 2016 08:30:16" | |
| }, | |
| "5081c5e5-e101-43eb-8e59-4e197f22a0d0"": { | |
| "name": "gate-horizon-pep8", | |
| "url": "https://ci.host.com/jobs/gate-horizon-pep8/2711", | |
| "value": -1, | |
| "reporter": "Jenkins Check", | |
| "comment": "Failed", | |
| "category": "cloud server", | |
| "duration": "3m 10s" | |
| "granted": "15 Mar 2016 08:10:41", | |
| } | |
| } | |
| ``` | |
| ### <a id="post-verify"> Post Verify | |
| __POST__ /changes/{change-id}/revisions/{revision-id}/@PLUGIN@~verifications | |
| Posts a verification result to a patchset. Each verification result is save as | |
| a unique entry in the database identified by a UUID. Results can be updated by | |
| posting with the UUID. | |
| The verification must be provided in the request body as a | |
| [VerifyInput](#verify-input) entity. | |
| #### Request | |
| ``` | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/verify-status~verifications HTTP/1.0 | |
| Content-Type: application/json;charset=UTF-8 | |
| ``` | |
| #### Example | |
| Post two verification results to patchset revision 14a95001c. | |
| _Notice_ two levels of quoting are required, one for the local shell, and | |
| another for the argument parser inside the Gerrit server. | |
| ``` | |
| curl -X POST --digest --user joe:secret --data-binary | |
| @verification_data.txt --header "Content-Type: application/json; charset=UTF-8" | |
| http://localhost:8080/a/changes/1000/revisions/14a95001c/verify-status~verifications | |
| $ cat verification_data.txt | |
| { | |
| "verifications": { | |
| "gate-horizon-python27": { | |
| "url": "https://ci.host.com/jobs/gate-horizon-python27/1711", | |
| "value": 1, | |
| "abstain": true, | |
| "reporter": "Jenkins Check", | |
| "comment": "Informational only", | |
| "category": "third party", | |
| "duration": "2m 40s" | |
| }, | |
| "gate-horizon-python34": { | |
| "url": "https://ci.host.com/jobs/gate-horizon-python34/1711", | |
| "value": -1, | |
| "abstain": false, | |
| "reporter": "Jenkins Check", | |
| "comment": "RuntimeError: File was not found", | |
| "category": "third party", | |
| "duration": "12m 20s" | |
| } | |
| } | |
| } | |
| ``` | |
| <a id="json-entities">JSON Entities | |
| ----------------------------------- | |
| ### <a id="verify-input"></a>VerifyInput | |
| The `VerifyInput` entity contains information for adding a verification | |
| to a revision. | |
| |Field Name | |Description| | |
| |:-----------|:----|:----------| | |
| |name |required|The name of this job| | |
| |value |required|The pass/fail result for this job| | |
| |abstain |optional|Whether the value counts as a vote (defaults to false)| | |
| |rerun |optional|Whether this result is from a re-test on the same patchset| | |
| |comment |optional|A short comment about this job| | |
| |url |optional|The url link to more info about this job| | |
| |reporter |optional|The user that verified this job| | |
| |category |optional|A category for this job| | |
| |duration |optional|The time it took to run this job| | |
| ### <a id="revision-info"></a>RevisionInfo | |
| The `RevisionInfo` entity contains information about a patch set. | |
| Not all fields are returned by default. Additional fields can | |
| be obtained by adding `o` parameters as described in | |
| [Query Changes](../../../Documentation/rest-api-changes.html#list-changes) | |
| |Field Name | |Description | | |
| |:-------------|:---|:-----------| | |
| |verifications |optional|The verifications on the patchset as a list of `VerificationInfo` entities| | |
| ### <a id="verification-info"></a>VerificationInfo | |
| The `VerificationInfo` entity describes a verification on a patch set. | |
| |Field Name |Description| | |
| |:----------|:----------| | |
| |name |The name of this job| | |
| |value |The pass/fail result for this job| | |
| |abstain |Whether the value counts as a vote| | |
| |rerun |Whether this result is from a re-test on the same patchset| | |
| |comment |A short comment about this job| | |
| |url |The url link to more info about this job| | |
| |reporter |The user that verified this job| | |
| |category |A category for this job| | |
| |duration |The time it took to run this job| | |
| |granted |The date this verification was recorded| | |
| ACCESS | |
| ------ | |
| Caller must be a member of a group that is granted the | |
| 'Save Verification Report' capability (provided by this plugin) in order to | |
| POST reports. | |
| SEE ALSO | |
| -------- | |
| * [Change related REST endpoints](../../../Documentation/rest-api-changes.html) | |
| * [Plugin Development](../../../Documentation/dev-plugins.html) | |
| * [REST API Development](../../../Documentation/dev-rest-api.html) | |
| GERRIT | |
| ------ | |
| Part of [Gerrit Code Review](../../../Documentation/index.html) |