src/main/resources/Documentation/rest-api-changes.md - plugins/verify-status - Git at Google

 @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)
	@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)