Review Request Resource¶

Provides information on review requests.

Review requests are one of the central concepts in Review Board. They represent code or files that are being placed up for review.

A review request has a number of fields that can be filled out, indicating the summary, description of the change, testing that was done, affected bugs, and more. These must be filled out through the associated Review Request Draft resource.

When a review request is published, it can be reviewed by users. It can then be updated, again through the Review Request Draft resource, or closed as submitted or discarded.

Details¶

Name	`review_request`
URI	`/api/review-requests/{review_request_id}/`
Token Policy ID	`review_request`
HTTP Methods	DELETE - Deletes the review request permanently. GET - Returns information on a particular review request. PUT - Updates the status of the review request.
Parent Resource	Review Request List Resource
Child Resources	Change List Resource Diff Context Resource Diff List Resource File Attachment List Resource Review List Resource Review Request Draft Resource Review Request Last Update Resource Screenshot List Resource
Anonymous Access	Yes, if anonymous site access is enabled

Fields¶

absolute_urlString	The absolute URL to the review request’s page on the site. Added in 2.0
approval_failureString	The reason why the review request was not approved. This will be `null` if approved. Added in 2.0
approvedBoolean	Whether the review request has been approved by reviewers. On a default install, a review request is approved if it has at least one Ship It! and no open issues. Extensions may change these requirements. Added in 2.0
blocksList of Review Request Resource	The list of review requests that this review request is blocking. Added in 1.7.9
branchString	The branch that the code was changed on or that the code will be committed to. This is a free-form field that can store any text.
bugs_closedList of String	The list of bugs closed or referenced by this change.
changenumInteger	Deprecated The change number that the review request represents. These are server-side repository-specific change numbers, and are not supported by all types of repositories. It may be `null`. This is deprecated in favor of the `commit_id` field. Deprecated in 2.0
close_descriptionRich Text	The text describing the closing of the review request. Added in 2.0.12
close_description_text_typeOne of `plain`, `markdown`, `html`	The current or forced text type for the `close_description` field. Added in 2.0.12
commit_idString	The commit that the review request represents. This obsoletes the `changenum` field. Added in 2.0
depends_onList of Review Request Resource	The list of review requests that this review request depends on. Added in 1.7.9
descriptionRich Text	The review request’s description.
description_text_typeOne of `plain`, `markdown`, `html`	The current or forced text type for the `description` field. Added in 2.0.12
extra_dataDictionary	Extra data as part of the review request. This can be set by the API or extensions. Added in 2.0
idInteger	The numeric ID of the review request.
issue_dropped_countInteger	The number of dropped issues on this review request Added in 2.0
issue_open_countInteger	The number of open issues on this review request Added in 2.0
issue_resolved_countInteger	The number of resolved issues on this review request Added in 2.0
last_updatedString	The date and time that the review request was last updated (in `YYYY-MM-DD HH:MM:SS` format).
publicBoolean	Whether or not the review request is currently visible to other users.
repositoryRepository Resource	The repository that the review request’s code is stored on.
ship_it_countInteger	The number of Ship Its given to this review request. Added in 2.0
statusOne of `discarded`, `pending`, `submitted`	The current status of the review request.
submitterUser Resource	The user who submitted the review request.
summaryString	The review request’s brief summary.
target_groupsList of Review Group Resource	The list of review groups who were requested to review this change.
target_peopleList of User Resource	The list of users who were requested to review this change.
testing_doneRich Text	The information on the testing that was done for the change.
testing_done_text_typeOne of `plain`, `markdown`, `html`	The current or forced text type for the `testing_done` field. Added in 2.0.12
text_typeOne of `plain`, `markdown`, `html`	Deprecated Formerly responsible for indicating the text type for text fields. Replaced by `close_description_text_type`, `description_text_type`, and `testing_done_text_type` in 2.0.12. Added in 2.0 Deprecated in 2.0.12
time_addedString	The date and time that the review request was added (in `YYYY-MM-DD HH:MM:SS` format).
urlString	Deprecated The URL to the review request’s page on the site. This is deprecated and will be removed in a future version. Added in 1.7.8 Deprecated in 2.0

Links¶

Name	Method	Resource
changes	GET	Change List Resource
delete	DELETE	Review Request Resource
diff_context	GET	Diff Context Resource
diffs	GET	Diff List Resource
draft	GET	Review Request Draft Resource
file_attachments	GET	File Attachment List Resource
last_update	GET	Review Request Last Update Resource
latest_diff	GET	Review Request Resource
reviews	GET	Review List Resource
screenshots	GET	Screenshot List Resource
self	GET	Review Request Resource
update	PUT	Review Request Resource

HTTP DELETE¶

Deletes the review request permanently.

This is a dangerous call to make, as it will delete the review request, associated screenshots, diffs, and reviews. There is no going back after this call is made.

Only users who have been granted the reviews.delete_reviewrequest permission (which includes administrators) can perform a delete on the review request.

After a successful delete, this will return HTTP 204 No Content.

Errors¶

100 - Does Not ExistHTTP 404 - Not Found	Object does not exist
101 - Permission DeniedHTTP 403 - Forbidden	You don’t have permission for this
103 - Not Logged InHTTP 401 - Unauthorized	You are not logged in

HTTP GET¶

Returns information on a particular review request.

This contains full information on the latest published review request.

If the review request is not public, then the client’s logged in user must either be the owner of the review request or must have the reviews.can_edit_reviewrequest permission set. Otherwise, an error will be returned.

Errors¶

100 - Does Not ExistHTTP 404 - Not Found	Object does not exist
101 - Permission DeniedHTTP 403 - Forbidden	You don’t have permission for this
103 - Not Logged InHTTP 401 - Unauthorized	You are not logged in

HTTP PUT¶

Updates the status of the review request.

The only supported update to a review request’s resource is to change the status, the associated server-side, change number, or to update information from the existing change number.

The status can be set in order to close the review request as discarded or submitted, or to reopen as pending.

For Perforce, a change number can either be changed to a new number, or the current change number can be passed. In either case, a new draft will be created or an existing one updated to include information from the server based on the change number. This behavior is deprecated, and instead, the commit_id field should be set on the draft.

Changes to a review request’s fields, such as the summary or the list of reviewers, is made on the Review Request Draft resource. This can be accessed through the draft link. Only when that draft is published will the changes end up back in this resource.

Extra data can be stored on the review request for later lookup by passing extra_data.key_name=value. The key_name and value can be any valid strings. Passing a blank value will remove the key. The extra_data. prefix is required.

Request Parameters¶

changenumInteger	Deprecated The optional change number to set or update. This can be used to re-associate with a new change number, or to create/update a draft with new information from the current change number. This only works with repositories that support server-side changesets. This is deprecated. Instead, set `commit_id` and `update_from_commit_id=1` on the draft. Added in 1.5.4 Deprecated in 2.0
close_descriptionRich Text	The description of the update. Should only be used if the review request have been submitted or discarded. This replaces the old `description` field. Added in 2.0.9
close_description_text_typeOne of `plain`, `markdown`	Deprecated The text type for the close description of the update field. Added in 2.0 Deprecated in 2.0.12
descriptionRich Text	Deprecated The description of the update. Should only be used if the review request have been submitted or discarded. This is deprecated. Instead, set `close_description`. Added in 1.6 Deprecated in 2.0.9
force_text_typeOne of `plain`, `markdown`, `html`	The text type, if any, to force for returned text fields. The contents will be converted to the requested type in the payload, but will not be saved as that type. Added in 2.0.9
statusOne of `discarded`, `pending`, `submitted`	The status of the review request. This can be changed to close or reopen the review request
text_typeOne of `plain`, `markdown`	Deprecated The text type for the close description of the update field. This is deprecated. Please use `close_description_text_type` instead. Added in 2.0 Deprecated in 2.0.12

Errors¶

100 - Does Not ExistHTTP 404 - Not Found	Object does not exist
101 - Permission DeniedHTTP 403 - Forbidden	You don’t have permission for this
103 - Not Logged InHTTP 401 - Unauthorized	You are not logged in
105 - Invalid Form DataHTTP 400 - Bad Request	One or more fields had errors

Examples¶

application/vnd.reviewboard.org.review-request+json¶

$ curl http://reviews.example.com/api/review-requests/8/ -H "Accept: application/json"

Vary: Accept, Cookie
ETag: 8e00a4c95187d9c41a1dbff39f731abcabf9556d
Content-Type: application/vnd.reviewboard.org.review-request+json
X-Content-Type-Options: nosniff

{
  "review_request": {
    "absolute_url": "http://reviews.example.com/r/8/", 
    "approval_failure": "The review request has not been marked \"Ship It!\"", 
    "approved": false, 
    "blocks": [], 
    "branch": "trunk", 
    "bugs_closed": [], 
    "changenum": null, 
    "close_description": null, 
    "close_description_text_type": "plain", 
    "commit_id": null, 
    "depends_on": [], 
    "description": "This is a test designed for interdiffs.", 
    "description_text_type": "plain", 
    "extra_data": {}, 
    "id": 8, 
    "issue_dropped_count": 0, 
    "issue_open_count": 0, 
    "issue_resolved_count": 0, 
    "last_updated": "2013-09-07T02:26:18Z", 
    "links": {
      "changes": {
        "href": "http://reviews.example.com/api/review-requests/8/changes/", 
        "method": "GET"
      }, 
      "delete": {
        "href": "http://reviews.example.com/api/review-requests/8/", 
        "method": "DELETE"
      }, 
      "diff_context": {
        "href": "http://reviews.example.com/api/review-requests/8/diff-context/", 
        "method": "GET"
      }, 
      "diffs": {
        "href": "http://reviews.example.com/api/review-requests/8/diffs/", 
        "method": "GET"
      }, 
      "draft": {
        "href": "http://reviews.example.com/api/review-requests/8/draft/", 
        "method": "GET"
      }, 
      "file_attachments": {
        "href": "http://reviews.example.com/api/review-requests/8/file-attachments/", 
        "method": "GET"
      }, 
      "last_update": {
        "href": "http://reviews.example.com/api/review-requests/8/last-update/", 
        "method": "GET"
      }, 
      "latest_diff": {
        "href": "http://example.com/api/review-requests/8/diffs/3/", 
        "method": "GET"
      }, 
      "repository": {
        "href": "http://reviews.example.com/api/repositories/1/", 
        "method": "GET", 
        "title": "Review Board SVN"
      }, 
      "reviews": {
        "href": "http://reviews.example.com/api/review-requests/8/reviews/", 
        "method": "GET"
      }, 
      "screenshots": {
        "href": "http://reviews.example.com/api/review-requests/8/screenshots/", 
        "method": "GET"
      }, 
      "self": {
        "href": "http://reviews.example.com/api/review-requests/8/", 
        "method": "GET"
      }, 
      "submitter": {
        "href": "http://reviews.example.com/api/users/admin/", 
        "method": "GET", 
        "title": "admin"
      }, 
      "update": {
        "href": "http://reviews.example.com/api/review-requests/8/", 
        "method": "PUT"
      }
    }, 
    "public": true, 
    "ship_it_count": 0, 
    "status": "pending", 
    "summary": "Interdiff Revision Test", 
    "target_groups": [], 
    "target_people": [
      {
        "href": "http://reviews.example.com/api/users/grumpy/", 
        "method": "GET", 
        "title": "grumpy"
      }
    ], 
    "testing_done": "", 
    "testing_done_text_type": "plain", 
    "text_type": null, 
    "time_added": "2013-08-07T02:01:21Z", 
    "url": "/r/8/"
  }, 
  "stat": "ok"
}