Jump to >

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

timestampString The date and time that the review was posted (in YYYY-MM-DD HH:MM:SS format).
userUser Resource The user who wrote the review.

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_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 http://reviews.example.com/api/review-requests/8/reviews/8/ -H "Accept: application/json"
Vary: Accept, Cookie
ETag: a52a1fdaf295fdc381665a18487cce216b607a38
Content-Type: application/vnd.reviewboard.org.review+json
X-Content-Type-Options: nosniff
{
  "review": {
    "absolute_url": "http://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": "http://reviews.example.com/api/review-requests/8/reviews/8/", 
        "method": "DELETE"
      }, 
      "diff_comments": {
        "href": "http://reviews.example.com/api/review-requests/8/reviews/8/diff-comments/", 
        "method": "GET"
      }, 
      "file_attachment_comments": {
        "href": "http://reviews.example.com/api/review-requests/8/reviews/8/file-attachment-comments/", 
        "method": "GET"
      }, 
      "general_comments": {
        "href": "http://reviews.example.com/api/review-requests/8/reviews/8/general-comments/", 
        "method": "GET"
      }, 
      "replies": {
        "href": "http://reviews.example.com/api/review-requests/8/reviews/8/replies/", 
        "method": "GET"
      }, 
      "screenshot_comments": {
        "href": "http://reviews.example.com/api/review-requests/8/reviews/8/screenshot-comments/", 
        "method": "GET"
      }, 
      "self": {
        "href": "http://reviews.example.com/api/review-requests/8/reviews/8/", 
        "method": "GET"
      }, 
      "update": {
        "href": "http://reviews.example.com/api/review-requests/8/reviews/8/", 
        "method": "PUT"
      }, 
      "user": {
        "href": "http://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"
}