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 Status Update List Resource

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
created_with_historyBoolean	Whether or not the review request was created with history support. A value of true indicates that the review request will have commits attached. Added in 4.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
issue_verifying_countInteger	The number of issues waiting for verification to resolve or drop on this review request Added in 3.0.3
last_updated ISO 8601 Date/Time	The date and time that the review request was last updated.
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_added ISO 8601 Date/Time	The date and time that the review request was added.
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
status_updates	GET	Status Update List 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
112 - OAuth2 Missing Scope ErrorHTTP 403 - Forbidden	Your OAuth2 token lacks the necessary scopes for this request.
113 - OAuth2 Access Denied ErrorHTTP 403 - Forbidden	OAuth2 token access for this resource is prohibited.

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
112 - OAuth2 Missing Scope ErrorHTTP 403 - Forbidden	Your OAuth2 token lacks the necessary scopes for this request.
113 - OAuth2 Access Denied ErrorHTTP 403 - Forbidden	OAuth2 token access for this resource is prohibited.

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 later lookup. See Storing/Accessing Extra Data for more information.

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
112 - OAuth2 Missing Scope ErrorHTTP 403 - Forbidden	Your OAuth2 token lacks the necessary scopes for this request.
113 - OAuth2 Access Denied ErrorHTTP 403 - Forbidden	OAuth2 token access for this resource is prohibited.
210 - Repository Information ErrorHTTP 500 - Internal Server Error	There was an error communicating with this repository.
216 - Unverified Host CertificateHTTP 403 - Forbidden	The HTTPS certificate on the host is unverified.

Examples¶

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

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

HTTP 200 OK
Content-Length: 2624
Content-Type: application/vnd.reviewboard.org.review-request+json
ETag: 28b57956b7dfb4d3fce10a609b17586948b15936
Vary: Accept, Cookie
X-Content-Type-Options: nosniff

{
  "review_request": {
    "absolute_url": "https://reviews.example.com/r/10/",
    "approval_failure": "The review request has not been marked \"Ship It!\"",
    "approved": false,
    "blocks": [],
    "branch": "",
    "bugs_closed": [],
    "changenum": null,
    "close_description": null,
    "close_description_text_type": "plain",
    "commit_id": null,
    "created_with_history": true,
    "depends_on": [],
    "description": "Test review request with history.",
    "description_text_type": "markdown",
    "extra_data": {
      "calculated_trophies": true,
      "local_branch": "master"
    },
    "id": 10,
    "issue_dropped_count": 0,
    "issue_open_count": 0,
    "issue_resolved_count": 0,
    "issue_verifying_count": 0,
    "last_updated": "2018-08-10T22:16:47Z",
    "links": {
      "changes": {
        "href": "https://reviews.example.com/api/review-requests/10/changes/",
        "method": "GET"
      },
      "delete": {
        "href": "https://reviews.example.com/api/review-requests/10/",
        "method": "DELETE"
      },
      "diff_context": {
        "href": "https://reviews.example.com/api/review-requests/10/diff-context/",
        "method": "GET"
      },
      "diffs": {
        "href": "https://reviews.example.com/api/review-requests/10/diffs/",
        "method": "GET"
      },
      "draft": {
        "href": "https://reviews.example.com/api/review-requests/10/draft/",
        "method": "GET"
      },
      "file_attachments": {
        "href": "https://reviews.example.com/api/review-requests/10/file-attachments/",
        "method": "GET"
      },
      "last_update": {
        "href": "https://reviews.example.com/api/review-requests/10/last-update/",
        "method": "GET"
      },
      "latest_diff": {
        "href": "http://example.com/api/review-requests/10/diffs/2/",
        "method": "GET"
      },
      "repository": {
        "href": "https://reviews.example.com/api/repositories/3/",
        "method": "GET",
        "title": "Git Repo"
      },
      "reviews": {
        "href": "https://reviews.example.com/api/review-requests/10/reviews/",
        "method": "GET"
      },
      "screenshots": {
        "href": "https://reviews.example.com/api/review-requests/10/screenshots/",
        "method": "GET"
      },
      "self": {
        "href": "https://reviews.example.com/api/review-requests/10/",
        "method": "GET"
      },
      "status_updates": {
        "href": "https://reviews.example.com/api/review-requests/10/status-updates/",
        "method": "GET"
      },
      "submitter": {
        "href": "https://reviews.example.com/api/users/doc/",
        "method": "GET",
        "title": "doc"
      },
      "update": {
        "href": "https://reviews.example.com/api/review-requests/10/",
        "method": "PUT"
      }
    },
    "public": true,
    "ship_it_count": 0,
    "status": "pending",
    "summary": "Review request with history",
    "target_groups": [
      {
        "href": "https://reviews.example.com/api/groups/devgroup/",
        "method": "GET",
        "title": "devgroup"
      }
    ],
    "target_people": [],
    "testing_done": "",
    "testing_done_text_type": "markdown",
    "text_type": null,
    "time_added": "2018-08-10T22:16:22Z",
    "url": "/r/10/"
  },
  "stat": "ok"
}