Describe how to add reviewers via REST
Change-Id: I7d4a31459d482b5feee0e50e2efe6289bcc41959
Signed-off-by: Edwin Kempin <edwin.kempin@sap.com>
diff --git a/Documentation/rest-api-changes.txt b/Documentation/rest-api-changes.txt
index e7904a2..e040a01 100644
--- a/Documentation/rest-api-changes.txt
+++ b/Documentation/rest-api-changes.txt
@@ -851,6 +851,94 @@
}
----
+[[add-reviewer]]
+POST /changes/\{change-id\}/reviewers (Add Reviewer)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Adds one user or all members of one group as reviewer to the change.
+
+The reviewer to be added to the change must be provided in the request
+body as a link:#reviewer-input[ReviewerInput] entity.
+
+.Request
+----
+ POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers HTTP/1.0
+ Content-Type: application/json;charset=UTF-8
+
+ {
+ "reviewer": "john.doe@example.com"
+ }
+----
+
+As response an link:#add-reviewer-result[AddReviewerResult] entity is
+returned that describes the newly added reviewers.
+
+.Response
+----
+ HTTP/1.1 200 OK
+ Content-Disposition: attachment
+ Content-Type: application/json;charset=UTF-8
+
+ )]}'
+ {
+ "reviewers": [
+ {
+ "kind": "gerritcodereview#reviewer",
+ "approvals": {
+ "Verified": " 0",
+ "Code-Review": " 0"
+ },
+ "_account_id": 1000096,
+ "name": "John Doe",
+ "email": "john.doe@example.com"
+ }
+ ]
+ }
+----
+
+If a group is specified, adding the group members as reviewers is an
+atomic operation. This means if an error is returned, none of the
+members are added as reviewer.
+
+If a group with many members is added as reviewer a confirmation may be
+required.
+
+.Request
+----
+ POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers HTTP/1.0
+ Content-Type: application/json;charset=UTF-8
+
+ {
+ "reviewer": "MyProjectVerifiers"
+ }
+----
+
+.Response
+----
+ HTTP/1.1 200 OK
+ Content-Disposition: attachment
+ Content-Type: application/json;charset=UTF-8
+
+ )]}'
+ {
+ "error": "The group My Group has 15 members. Do you want to add them all as reviewers?",
+ "confirm": true
+ }
+----
+
+To confirm the addition of the reviewers, resend the request with the
+`confirm` flag being set.
+
+.Request
+----
+ POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers HTTP/1.0
+ Content-Type: application/json;charset=UTF-8
+
+ {
+ "reviewer": "MyProjectVerifiers",
+ "confirm": true
+ }
+----
+
[[ids]]
IDs
@@ -912,6 +1000,26 @@
requested.
|===========================
+[[add-reviewer-result]]
+AddReviewerResult
+~~~~~~~~~~~~~~~~~
+The `AddReviewerResult` entity describes the result of adding a
+reviewer to a change.
+
+[options="header",width="50%",cols="1,^1,5"]
+|===========================
+|Field Name ||Description
+|`reviewers` |optional|
+The newly added reviewers as a list of link:#reviewer-info[
+ReviewerInfo] entities.
+|`error` |optional|
+Error message explaining why the reviewer could not be added. +
+If a group was specified in the input and an error is returned, it
+means that none of the members were added as reviewer.
+|`confirm` |`false` if not set|
+Whether adding the reviewer requires confirmation.
+|===========================
+
[[approval-info]]
ApprovalInfo
~~~~~~~~~~~~
@@ -1149,6 +1257,28 @@
approval values ("`-2`", "`-1`", " `0`", "`+1`", "`+2`").
|==========================
+[[reviewer-input]]
+ReviewerInput
+~~~~~~~~~~~~~
+The `ReviewerInput` entity contains information for adding a reviewer
+to a change.
+
+[options="header",width="50%",cols="1,^1,5"]
+|===========================
+|Field Name ||Description
+|`reviewer` ||
+The link:rest-api-accounts.html#account-id[ID] of one account that
+should be added as reviewer or the link:rest-api-groups.html#group-id[
+ID] of one group for which all members should be added as reviewers. +
+If an ID identifies both an account and a group, only the account is
+added as reviewer to the change.
+|`confirmed` |optional|
+Whether adding the reviewer is confirmed. +
+The Gerrit server may be configured to
+link:config-gerrit.html#addreviewer.maxWithoutConfirmation[require a
+confirmation] when adding a group as reviewer that has many members.
+|===========================
+
[[revision-info]]
RevisionInfo
~~~~~~~~~~~~
