Crucible 2.2 : Review Service - Reviews
This page last changed on Nov 19, 2009 by edawson.
On this page:
ReviewsAdd Changeset To ReviewPOST /reviews-v1/<review id>/addChangeset Add the revisions in a set of changesets to an existing review. Status Code: Example XML Return Data: <addChangeset> <repository>aRepositoryName</repository> <changesets> <changesetData> <id>...the id...</id> </changesetData> ... more change sets ... </changesets> </addChangeset> {"addChangeset": { "repository":"Local", "changesets": { "changesetData":[ {"id":234},{"id":237}, ...more change sets...]} }} The response is the reviewData structure of the review. Add Patch Revisions To ReviewPOST /reviews-v1/<review id>/addPatch Add the revisions in a patch to an existing review. Status Code: Example XML Request Data: <addPatch> <repository>aRepositoryName</repository> <patch> <![CDATA[ ... text of patch goes here ... ]]> </patch> </addPatch> {"addPatch":{"repository":"aRepositoryName","patch":"... text of patch goes here ..."}} The response is the reviewData structure of the review. Upload Files To ReviewPOST /reviews-v1/<review id>/addFile Uploads a local file to the review. In contrast to a patch, files can be either binary or text. Depending on the filetype, size and contents, Crucible may be able to display either parts, or the entire file in the review. It is possible to upload two versions of the file, in which case Crucible will display a diff and report that the file was modified. When only a single file is uploaded, Crucible treats the file as newly added. This action returns the ReviewData document on success. This resources uses multipart form-data to receive the file(s), character set indication and optional comments (it does not expect an XML document with embedded files, as that would require the client to first encode the files in Base64). Making a multipart form-data request can be done manually, but you will probably want to use a library. During testing it is inconvenient to let your browser generate the requests using the test html form below: Example HTML Form for Testing REST-Based File Uploads <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <head><title>Rest File Upload Test</title></head> <body> <!-- Point the URL to the review you want to upload to. --> <form action="http://hostname:port/rest-service/reviews-v1/<review id>/addFile" enctype="multipart/form-data" method="POST"> <table> <tr> <td>File (required):</td> <td><input name="file" type="file"/></td> </tr> <tr> <td>Diff to (optional):</td> <td><input name="diffFile" type="file"/></td> </tr> <tr> <td>Character Set (optional):</td> <td><input name="charset" type="text" value="UTF-8"/></td> </tr> <tr> <td>Comments (optional):</td> <td><input type="text" name="comments"/></td> </tr> <tr><td><input type="submit" value="Upload"/></td></tr> </table> </form> </body> </html>
When uploading files, make sure you (or your http client library) supplies the proper Content-Type header. For text files, use "text/plain". Crucible will preserve the original file name. Status Code: Create ReviewPOST /reviews-v1 Create a review. A review can be created in one of three ways(see examples). Status Code: Example XML Request Data: XML <createReview> <reviewData> ... </reviewData> </createReview> JSON {createReview: {"reviewData": { "allowReviewersToJoin":false, "author":{"userName":"joe"}, "creator":{"userName":"joe"}, "moderator":{"userName":"matt"}, "description":"Review objectives", "metricsVersion":1, "name":"Stuff to review", "projectKey":"CR" }} XML <createReview> <reviewData> ... </reviewData> <patch> <![CDATA[ ... text of patch goes here ... ]]> </patch> </createReview> JSON {createReview: {"reviewData": { "allowReviewersToJoin":false, "author":{"userName":"joe"}, "creator":{"userName":"joe"}, "moderator":{"userName":"matt"}, "description":"", "metricsVersion":1, "name":"readme ", "projectKey":"CR"}, "patch":"... text of patch goes here ..."} } XML <createReview> <reviewData> ... </reviewData> <changesets> <changesetData> <id>...the id...</id> </changesetData> ... more changesets ... </changesets> </createReview> JSON {createReview: {"reviewData": { "allowReviewersToJoin":false, "author":{"userName":"joe"}, "creator":{"userName":"joe"}, "moderator":{"userName":"matt"}, "description":"", "metricsVersion":1, "name":"readme ", "projectKey":"CR"}, "changesets": { "changesetData":[{"id":"234"}, {"id":"237"}],"repository":"Local"} } In all these cases, the reviewData structure shouldn't have the permaId or state attributes set. The response is a reviewData structure fully populated.| Delete ReviewDELETE /reviews-v1/<id> Delete a review. The review must have been abandoned. Status Code: Get All ReviewsGET /reviews-v1?state=<states> Get all reviews as a list of ReviewData structures. Note that this may return a lot of data, so using /reviews-v1/filter/<filter> (see below) is usually better. The state parameter is a comma separated list of state names from the set Draft, Approval, Review, Summarize, Closed, Dead, Rejected, Unknown. Status Code: Example XML Return Data: <reviews> <reviewData> ... </reviewData> ... </reviews> {"reviews": { "reviewData": [ {"allowReviewersToJoin":true, ... }, ...] } } Get All Reviews (limited)GET /reviews-v1/details?state=<states> Get all reviews as a list of DetailedReviewData structures. The state parameter is a comma separated list of state names from the set Draft, Approval, Review, Summarize, Closed, Dead, Rejected, Unknown. Note that the reviewItems list in the detailedReviewData elements will not appear because this URL retrieves multiple reviews. Status Code: Example XML Return Data: <detailedReviews> <detailedReviewData> ... </detailedReviewData> ... </detailedReviews> {"detailedReviews": { "detailedReviewData": [ {"allowReviewersToJoin":true, ... }, ...] } } Get Allowed Review ActionsGET /reviews-v1/<id>/actions Get a list of the actions which the current user is allowed to perform on the review. This shows actions the user has permission to perform - the review may not be in a suitable state for all these actions to be performed. Status Code: Example XML Return Data: <actions> <actionData> <name>action:summarizeReview</name> </actionData> <actionData> <name>action:viewReview</name> </actionData> <actionData> <name>action:approveReview</name> </actionData> <actionData> <name>action:closeReview</name> </actionData> <actionData> <name>action:modifyReviewFiles</name> </actionData> <actionData> <name>action:rejectReview</name> </actionData> <actionData> <name>action:deleteReview</name> </actionData> <actionData> <name>action:createReview</name> </actionData> <actionData> <name>action:recoverReview</name> </actionData> <actionData> <name>action:commentOnReview</name> </actionData> <actionData> <name>action:reopenReview</name> </actionData> <actionData> <name>action:abandonReview</name> </actionData> <actionData> <name>action:submitReview</name> </actionData> </actions> {"actions": { "actionData": [ {"name":"action:modifyReviewFiles"}, {"name":"action:recoverReview"}, {"name":"action:createReview"}, {"name":"action:rejectReview"}, {"name":"action:deleteReview"}, {"name":"action:abandonReview"}, {"name":"action:closeReview"}, {"name":"action:reopenReview"}, {"name":"action:approveReview"}, {"name":"action:submitReview"}, {"name":"action:summarizeReview"}, {"name":"action:viewReview"}, {"name":"action:commentOnReview"}] }} Get Allowed Review TransitionsGET /reviews-v1/<id>/transitions Get a list of the actions which the current user can perform on this review, given its current state and the user's permissions. Status Code: Example XML Return Data: <transitions> <transitionData> <name>action:summarizeReview</name> </transitionData> <transitionData> <name>action:abandonReview</name> </transitionData> </transitions> {"transitions": { "transitionData": [ {"name":"action:approveReview"}, {"name":"action:abandonReview"}] }} Get ReviewGET /reviews-v1/<id> Get a single review. Status Code: Example XML Return Data: <reviewData> ... </reviewData> {"reviewData": { "allowReviewersToJoin":false, ... }} Get Review DetailsGET /reviews-v1/filter/<filter>/details Get details of all the reviews which match the given filter. See above for filter names. Status Code: Example XML Return Data: <detailedReviews> <detailedReviewData> ... </detailedReviewData> ... </detailedReviews> {"detailedReviews": { "detailedReviewData": [ {"allowReviewersToJoin":true, ... }, ...] } } Get Review Details by PathGET /reviews-v1/search/<repository>/details?path=<path> Return a list of Review details which include a particular file. The path parameter must be the full path name of a file in repository, with no leading slash. Status Code: Example XML Return Data: <detailedReviews> <detailedReviewData> ... </detailedReviewData> ... </detailedReviews> {"detailedReviews": { "detailedReviewData": [ {"allowReviewersToJoin":true, ... }, ...] } } Get Review Details through Custom Filter CriteriaGET /reviews-v1/filter/details?title=..&author=..&moderator=..&creator=..&reviewer=..&orRoles=true|false&complete=true|false&allReviewersComplete=true|false&project=.. Get details of all the reviews which match the specified filter criteria. Criteria are supplied as normal query parameters in the URL. Filter criteria are:
Status Code: Example XML Return Data: <reviews> <reviewData> ... </reviewData> ... </reviews> {"reviews": { "reviewData": [ {"allowReviewersToJoin":true, ... }, ...] } } Get Reviews by FilterGET /reviews-v1/filter/<filter> Get all the reviews which match the given filter, for the current user. Filter names are:
Status Code: Example XML Return Data: <reviews> <reviewData> ... </reviewData> ... </reviews> {"reviews": { "reviewData": [ {"allowReviewersToJoin":true, ... }, ...] } } Get Reviews by PathGET /reviews-v1/search/<repository>?path=<path> Return a list of Reviews which include a particular file. The path parameter must be the full path name of a file in repository, with no leading slash. Status Code: Example XML Return Data: <reviews> <reviewData> ... </reviewData> ... </reviews> {"reviews": { "reviewData": [ {"allowReviewersToJoin":true, ... }, ...] } } Get Reviews through Custom Filter CriteriaGET /reviews-v1/filter?title=..&author=..&moderator=..&creator=..&reviewer=..&orRoles=true|false&complete=true|false&allReviewersComplete=true|false&project=.. Get all the reviews which match the specified filter criteria. Criteria are supplied as normal query parameters in the URL. Filter criteria are:
Status Code: Example XML Return Data: <reviews> <reviewData> ... </reviewData> ... </reviews> {"reviews": { "reviewData": [ {"allowReviewersToJoin":true, ... }, ...] } } Get Single Review DetailsGET /reviews-v1/<id>/details Get details of a single review. Status Code: Example XML Return Data: <detailedReviewData> ... </detailedReviewData> {"detailedReviewData": { "allowReviewersToJoin":false, ... }} Get Version InfoGET /reviews-v1/versionInfo Returns the release number and build date of Crucible. Status Code: Example XML Return Data: <versionInfo> <buildDate>2008-10-28</buildDate> <releaseNumber>1.6.3</releaseNumber> </versionInfo> {"versionInfo":{"buildDate":"2008-10-28","releaseNumber":"1.6.3"}} |
![]() |
Document generated by Confluence on Feb 23, 2010 02:04 |