Review Resource¶

Provides information on reviews made on a review request.

Each review can contain zero or more comments on diffs, screenshots, file attachments or general comments not tied to any code or file. It may also have text preceding the comments (the body_top field), and text following the comments (body_bottom).

A review may have replies made. Replies are flat, not threaded. Like a review, there may be body text and there may be comments (which are replies to comments on the parent review).

If the ship_it field is true, then the reviewer has given their approval of the change, once all issues raised on comments have been addressed.

Details¶

Name	`review`
URI	`/api/review-requests/{review_request_id}/reviews/{review_id}/`
Token Policy ID	`review`
HTTP Methods	DELETE - Deletes the draft review. GET - Returns information on a particular review. PUT - Updates the fields of an unpublished review.
Parent Resource	Review List Resource
Child Resources	Review Diff Comment List Resource Review File Attachment Comment List Resource Review General Comment List Resource Review Reply List Resource Review Screenshot Comment List Resource

Fields¶

absolute_urlString	The absolute URL to the review request’s page on the site. Added in 3.0
body_bottomRich Text	The review content below the comments.
body_bottom_text_typeOne of `plain`, `markdown`, `html`	The current or forced text type for the `body_bottom` field. Added in 2.0.12
body_topRich Text	The review content above the comments.
body_top_text_typeOne of `plain`, `markdown`, `html`	The current or forced text type for the `body_top` field. Added in 2.0.12
extra_dataDictionary	Extra data as part of the review. This can be set by the API or extensions. Added in 2.0
idInteger	The numeric ID of the review.
publicBoolean	Whether or not the review is currently visible to other users.
ship_itBoolean	Whether or not the review has been marked “Ship It!”
text_typeOne of `plain`, `markdown`, `html`	Deprecated Formerly responsible for indicating the text type for text fields. Replaced by `body_top_text_type` and `body_bottom_text_type` in 2.0.12. Added in 2.0 Deprecated in 2.0.12
timestampISO 8601 Date/Time	The date and time that the review was posted.
userUser Resource	The user who wrote the review.

Links¶

Name	Method	Resource
delete	DELETE	Review Resource
diff_comments	GET	Review Diff Comment List Resource
file_attachment_comments	GET	Review File Attachment Comment List Resource
general_comments	GET	Review General Comment List Resource
replies	GET	Review Reply List Resource
screenshot_comments	GET	Review Screenshot Comment List Resource
self	GET	Review Resource
update	PUT	Review Resource

HTTP DELETE¶

Deletes the draft review.

This only works for draft reviews, not public reviews. It will delete the review and all comments on it. This cannot be undone.

Only the user who owns the draft can delete it.

Upon deletion, 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.

If the review is not public, then the client’s logged in user must either be the owner of the review. 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 fields of an unpublished review.

Only the owner of a review can make changes. One or more fields can be updated at once.

The only special field is public, which, if set to true, will publish the review. The review will then be made publicly visible. Once public, the review cannot be modified or made private again with the exception of removing a ship it from review.

Request Parameters¶

body_bottomRich Text	The review content below the comments.
body_bottom_text_typeOne of `plain`, `markdown`	The text type used for the `body_bottom` field. Added in 2.0.12
body_topRich Text	The review content above the comments.
body_top_text_typeOne of `plain`, `markdown`	The text type used for the `body_top` field. Added in 2.0.12
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
publicBoolean	Whether or not to make the review public. If a review is public, it cannot be made private again.
publish_and_archiveBoolean	If true, the review will be archived after it is published. Added in 4.0
publish_to_owner_onlyBoolean	If true, the review will only send an e-mail to the owner of the review request. Added in 3.0
ship_itBoolean	Whether or not to mark the review “Ship It!”
text_typeOne of `plain`, `markdown`	Deprecated The mode for the `body_top` and `body_bottom` text fields. This is deprecated. Please use `body_top_text_type` and `body_bottom_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.
232 - Ship-It Revocation ErrorHTTP 500 - Internal Server Error	An error occurred while revoking the Ship It for a review.

Examples¶

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

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

HTTP 200 OK
Content-Length: 1357
Content-Type: application/vnd.reviewboard.org.review+json
ETag: 9df8ee8d8fd5a9e9e634b51f45a5938c12c85527
Vary: Accept, Cookie
X-Content-Type-Options: nosniff

{
  "review": {
    "absolute_url": "https://reviews.example.com/r/8/#review8", 
    "body_bottom": "", 
    "body_bottom_text_type": "plain", 
    "body_top": "", 
    "body_top_text_type": "plain", 
    "extra_data": {}, 
    "id": 8, 
    "links": {
      "delete": {
        "href": "https://reviews.example.com/api/review-requests/8/reviews/8/", 
        "method": "DELETE"
      }, 
      "diff_comments": {
        "href": "https://reviews.example.com/api/review-requests/8/reviews/8/diff-comments/", 
        "method": "GET"
      }, 
      "file_attachment_comments": {
        "href": "https://reviews.example.com/api/review-requests/8/reviews/8/file-attachment-comments/", 
        "method": "GET"
      }, 
      "general_comments": {
        "href": "https://reviews.example.com/api/review-requests/8/reviews/8/general-comments/", 
        "method": "GET"
      }, 
      "replies": {
        "href": "https://reviews.example.com/api/review-requests/8/reviews/8/replies/", 
        "method": "GET"
      }, 
      "screenshot_comments": {
        "href": "https://reviews.example.com/api/review-requests/8/reviews/8/screenshot-comments/", 
        "method": "GET"
      }, 
      "self": {
        "href": "https://reviews.example.com/api/review-requests/8/reviews/8/", 
        "method": "GET"
      }, 
      "update": {
        "href": "https://reviews.example.com/api/review-requests/8/reviews/8/", 
        "method": "PUT"
      }, 
      "user": {
        "href": "https://reviews.example.com/api/users/admin/", 
        "method": "GET", 
        "title": "admin"
      }
    }, 
    "public": true, 
    "ship_it": false, 
    "text_type": null, 
    "timestamp": "2010-08-28T02:25:31Z"
  }, 
  "stat": "ok"
}