Jump to >

This documentation covers Review Board 2.0. You can see the latest Review Board documentation or all other versions.

Review Request Draft Resource

An editable draft of a review request.

This resource is used to actually modify a review request. Anything made in this draft can be published in order to become part of the public review request, or it can be discarded.

Any POST or PUTs on this draft will cause the draft to be created automatically. An initial POST is not required.

There is only ever a maximum of one draft per review request.

In order to access this resource, the user must either own the review request, or it must have the reviews.can_edit_reviewrequest permission set.

Details

Name draft
URI /api/review-requests/{review_request_id}/draft/
HTTP Methods
  • DELETE - Deletes a draft of a review request.
  • GET - Returns the current draft of a review request.
  • PUT - Updates a draft of a review request.
Parent Resource Review Request Resource
Child Resources
Anonymous Access No

Fields

branchString The branch name.
bugs_closedString The new list of bugs closed or referenced by this change.
changedescriptionRich Text A custom description of what changes are being made in this update. It often will be used to describe the changes in the diff.
changedescription_text_typeOne of plain, markdown, html

The current or forced text type for the changedescription field.

Added in 2.0.12

commit_idString

The updated ID of the commit this review request is based upon.

Added in 2.0

depends_onList of Review Request Resource The list of review requests that this review request depends on.
descriptionRich Text The new review request 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 draft. This can be set by the API or extensions.
idInteger The numeric ID of the draft.
last_updatedString The date and time that the draft was last updated (in YYYY-MM-DD HH:MM:SS format).
publicBoolean Whether or not the draft is public. This will always be false up until the time it is first made public. At that point, the draft is deleted.
review_requestReview Request Resource The review request that owns this draft.
summaryString The new review request summary.
target_groupsString A comma-separated list of review groups that will be on the reviewer list.
target_peopleString A comma-separated list of users that will be on a reviewer list.
testing_doneRich Text The new testing done text.
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 changedescription_text_type, description_text_type, and testing_done_text_type in 2.0.12.

Added in 2.0

Deprecated in 2.0.12

HTTP DELETE

Deletes a draft of a review request.

This is equivalent to pressing Discard Draft in the review request’s page. It will simply erase all the contents of the draft.

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 the current draft of a review request.

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 a draft of a review request.

This will update the draft with the newly provided data.

Most of the fields correspond to fields in the review request, but there is one special one, public. When public is set to true, the draft will be published, moving the new content to the review request itself, making it public, and sending out a notification (such as an e-mail) if configured on the server. The current draft will then be deleted.

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

branchString The new branch name.
bugs_closedString A comma-separated list of bug IDs.
changedescriptionRich Text The change description for this update.
changedescription_text_typeOne of plain, markdown

The text type used for the changedescription field.

Added in 2.0.12

commit_idString

The updated ID of the commit this review request is based upon.

Added in 2.0

depends_onString The new list of dependencies of this review request.
descriptionRich Text The new review request description.
description_text_typeOne of plain, markdown

The text type used for the description 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.
publicBoolean Whether or not to make the review public. If a review is public, it cannot be made private again.
summaryString The new review request summary.
target_groupsString A comma-separated list of review groups that will be on the reviewer list.
target_peopleString A comma-separated list of users that will be on a reviewer list.
testing_doneRich Text The new testing done text.
testing_done_text_typeOne of plain, markdown

The text type used for the testing_done field.

Added in 2.0.12

text_typeOne of plain, markdown Deprecated

The mode for the changedescription, description, and testing_done fields.

This is deprecated. Please use changedescription_text_type, description_text_type, and testing_done_text_type instead.

Added in 2.0

Deprecated in 2.0.12

update_from_commit_idBoolean

If true, and if commit_id is provided, the review request information and (when supported) the diff will be updated based on the commit ID.

Added in 2.0

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
203 - Invalid Change NumberHTTP 404 - Not Found The commit ID specified could not be found.
225 - Publish ErrorHTTP 500 - Internal Server Error An error occurred during publishing.
227 - Commit ID Already ExistsHTTP 409 - Conflict Review request with this commit ID already exists in the repository.

Examples

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

$ curl http://reviews.example.com/api/review-requests/8/draft/ -H "Accept: application/json"
Vary: Accept, Cookie
ETag: 89d328522e4e080118a804f4f32655e92c224abf
Content-Type: application/vnd.reviewboard.org.review-request-draft+json
X-Content-Type-Options: nosniff
{
  "draft": {
    "branch": "master", 
    "bugs_closed": [
      "12", 
      "34"
    ], 
    "changedescription": "", 
    "changedescription_text_type": "plain", 
    "commit_id": null, 
    "depends_on": [], 
    "description": "This is the new description.", 
    "description_text_type": "plain", 
    "extra_data": {}, 
    "id": 1, 
    "last_updated": "2010-08-16T00:47:29Z", 
    "links": {
      "delete": {
        "href": "http://reviews.example.com/api/review-requests/8/draft/", 
        "method": "DELETE"
      }, 
      "draft_diffs": {
        "href": "http://reviews.example.com/api/review-requests/8/draft/diffs/", 
        "method": "GET"
      }, 
      "draft_file_attachments": {
        "href": "http://reviews.example.com/api/review-requests/8/draft/file-attachments/", 
        "method": "GET"
      }, 
      "draft_screenshots": {
        "href": "http://reviews.example.com/api/review-requests/8/draft/screenshots/", 
        "method": "GET"
      }, 
      "review_request": {
        "href": "http://reviews.example.com/api/review-requests/8/", 
        "method": "GET", 
        "title": "Interdiff Revision Test"
      }, 
      "self": {
        "href": "http://reviews.example.com/api/review-requests/8/draft/", 
        "method": "GET"
      }, 
      "update": {
        "href": "http://reviews.example.com/api/review-requests/8/draft/", 
        "method": "PUT"
      }
    }, 
    "public": false, 
    "summary": "This is the new summary", 
    "target_groups": [], 
    "target_people": [
      {
        "href": "http://reviews.example.com/api/users/grumpy/", 
        "method": "GET", 
        "title": "grumpy"
      }
    ], 
    "testing_done": "This is the new testing that was done.", 
    "testing_done_text_type": "plain", 
    "text_type": null
  }, 
  "stat": "ok"
}