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/`
Token Policy ID	`review_request_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	Draft Diff List Resource Draft File Attachment List Resource Draft Screenshot List Resource

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. Added in 1.7.8
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. Added in 2.0
idInteger	The numeric ID of the draft.
last_updated ISO 8601 Date/Time	The date and time that the draft was last updated.
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.
submitterString	The user who submitted the review request.
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

Links¶

Name	Method	Resource
delete	DELETE	Review Request Draft Resource
draft_diffs	GET	Draft Diff List Resource
draft_file_attachments	GET	Draft File Attachment List Resource
draft_screenshots	GET	Draft Screenshot List Resource
self	GET	Review Request Draft Resource
update	PUT	Review Request Draft Resource

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

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. Added in 1.7.8
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. 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_as_ownerBoolean	Publish on behalf of the owner of the review request. If setting `submitter`, this will publish on behalf of the previous owner. Added in 3.0.6
submitterString	The user who submitted the review request. Added in 3.0
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
trivialBoolean	Determines if the review request publish will not send an email. Added in 2.5
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
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.
203 - Invalid Change NumberHTTP 404 - Not Found	The commit ID specified could not be found.
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.
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.’,)

Examples¶

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

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

HTTP 200 OK
Content-Length: 1554
Content-Type: application/vnd.reviewboard.org.review-request-draft+json
ETag: 356c12d7afea85c4978a69c41975b5f39a967d12
Vary: Accept, Cookie
X-Content-Type-Options: nosniff

{
  "draft": {
    "branch": "",
    "bugs_closed": [],
    "changedescription": "",
    "changedescription_text_type": "plain",
    "commit_id": null,
    "depends_on": [],
    "description": "Test review request with history.",
    "description_text_type": "markdown",
    "extra_data": {
      "calculated_trophies": true,
      "local_branch": "master"
    },
    "id": 2,
    "last_updated": "2018-08-10T22:16:56Z",
    "links": {
      "delete": {
        "href": "https://reviews.example.com/api/review-requests/10/draft/",
        "method": "DELETE"
      },
      "draft_diffs": {
        "href": "https://reviews.example.com/api/review-requests/10/draft/diffs/",
        "method": "GET"
      },
      "draft_file_attachments": {
        "href": "https://reviews.example.com/api/review-requests/10/draft/file-attachments/",
        "method": "GET"
      },
      "draft_screenshots": {
        "href": "https://reviews.example.com/api/review-requests/10/draft/screenshots/",
        "method": "GET"
      },
      "review_request": {
        "href": "https://reviews.example.com/api/review-requests/10/",
        "method": "GET",
        "title": "Review request with history"
      },
      "self": {
        "href": "https://reviews.example.com/api/review-requests/10/draft/",
        "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/draft/",
        "method": "PUT"
      }
    },
    "public": false,
    "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
  },
  "stat": "ok"
}