This page last changed on Nov 19, 2009 by edawson.
The content on this page is deprecated. Please see the separate documentation space for developer reference material about FishEye and Crucible.

On this page:

Reviews

Add Changeset To Review


URL:

POST /reviews-v1/<review id>/addChangeset

Description:
Add the revisions in a set of changesets to an existing review.

Status Code:
200 (OK) on success.

Example XML Return Data:

<addChangeset>
  <repository>aRepositoryName</repository>
  <changesets>
    <changesetData>
      <id>...the id...</id>
    </changesetData>
    ... more change sets ...
  </changesets>
</addChangeset>

Example JSON Return Data:

{"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 Review


URL:

POST /reviews-v1/<review id>/addPatch

Description:
Add the revisions in a patch to an existing review.

Status Code:
200 (OK) on success.

Example XML Request Data:

<addPatch>
  <repository>aRepositoryName</repository>
  <patch>
    <![CDATA[
... text of patch goes here ...
    ]]>
  </patch>
</addPatch>

Example JSON Request Data:

{"addPatch":{"repository":"aRepositoryName","patch":"... text of patch goes here ..."}}


The response is the reviewData structure of the review.

Upload Files To Review


URL:

POST /reviews-v1/<review id>/addFile

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

The form requests understands the following 4 fields:

  • file - the file to add to the review (required)
  • diffFile - if supplied, Crucible will use this file as the base for a diff with file
  • charset - if supplied, specifies the character set of the (text)file (when omitted, the server's default character set will be used)
  • comments - optional user string that is stored along with the file

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:
201 (Created) on success.
The response is the reviewItemData structure describing the new item. Also, the Location response header is present and contains the PermId URL of the new item.

Create Review


URL:

POST /reviews-v1

Description:
Create a review. A review can be created in one of three ways(see examples).

Status Code:
201 (Created) on success. The reponse will contain the Location response header with the URL of the newly created resource.

Example XML Request Data:
1. An empty review, i.e. no revisions in the review. This uses the request below:

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

2. A patch review, containing diffs from a patch file, e.g. created by svn diff >patch.txt (note that the text of the patch must be properly escaped in the JSON object):

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 ..."}
}

3. A review containing revisions from a set of changesets. XML/JSON:

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 Review


URL:

DELETE /reviews-v1/<id>

Description:
Delete a review. The review must have been abandoned.

Status Code:
204 (No Content) on success.

Get All Reviews


URL:

GET /reviews-v1?state=<states>

Description:
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:
200 (OK) on success.

Example XML Return Data:

<reviews>
  <reviewData>
    ...
  </reviewData>
  ...
</reviews>

Example JSON Return Data:

{"reviews": {
  "reviewData": [
    {"allowReviewersToJoin":true,
     ...
    }, ...]
  }
}



Get All Reviews (limited)


URL:

GET /reviews-v1/details?state=<states>

Description:
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:
200 (OK) on success.

Example XML Return Data:

<detailedReviews>
  <detailedReviewData>
    ...
  </detailedReviewData>
  ...
</detailedReviews>

Example JSON Return Data:

{"detailedReviews": {
  "detailedReviewData": [
    {"allowReviewersToJoin":true,
     ...
    }, ...]
  }
}



Get Allowed Review Actions


URL:

GET /reviews-v1/<id>/actions

Description:
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:
200 (OK) on success.

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>

Example JSON Return Data:

{"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 Transitions


URL:

GET /reviews-v1/<id>/transitions

Description:
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:
200 (OK) on success.

Example XML Return Data:

<transitions>
  <transitionData>
    <name>action:summarizeReview</name>
  </transitionData>
  <transitionData>
    <name>action:abandonReview</name>
  </transitionData>
</transitions>

Example JSON Return Data:

{"transitions": {
  "transitionData": [
    {"name":"action:approveReview"},
    {"name":"action:abandonReview"}]
}}



Get Review


URL:

GET /reviews-v1/<id>

Description:
Get a single review.

Status Code:
200 (OK) on success.

Example XML Return Data:

<reviewData>
  ...
</reviewData>

Example JSON Return Data:

{"reviewData": {
  "allowReviewersToJoin":false,
  ...
}}



Get Review Details


URL:

GET /reviews-v1/filter/<filter>/details

Description:
Get details of all the reviews which match the given filter. See above for filter names.

Status Code:
200 (OK) on success.

Example XML Return Data:

<detailedReviews>
  <detailedReviewData>
    ...
  </detailedReviewData>
  ...
</detailedReviews>

Example JSON Return Data:

{"detailedReviews": {
  "detailedReviewData": [
    {"allowReviewersToJoin":true,
     ...
    }, ...]
  }
}



Get Review Details by Path


URL:

GET /reviews-v1/search/<repository>/details?path=<path>

Description:
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:
200 (OK) on success.

Example XML Return Data:

<detailedReviews>
  <detailedReviewData>
    ...
  </detailedReviewData>
  ...
</detailedReviews>

Example JSON Return Data:

{"detailedReviews": {
  "detailedReviewData": [
    {"allowReviewersToJoin":true,
     ...
    }, ...]
  }
}



Get Review Details through Custom Filter Criteria


URL:

GET /reviews-v1/filter/details?title=..&author=..&moderator=..&creator=..&reviewer=..&orRoles=true|false&complete=true|false&allReviewersComplete=true|false&project=..

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

  • title - Reviews whose title contain this substring.
  • author - Reviews authored by this user.
  • moderator - Reviews moderated by this user.
  • creator - Reviews created by this user.
  • reviewer - Reviews reviewed by this user.
  • orRoles - Whether to the value for author, creator, moderator and reviewer should be combined using OR (orRoles=true) or AND (orRoles=false).
  • complete - Reviews that the specified reviewer has completed.
  • allReviewersComplete - Reviews that all reviewers have completed.
  • project - Reviews for the specified project.

Status Code:
200 (OK) on success.

Example XML Return Data:

<reviews>
  <reviewData>
    ...
  </reviewData>
  ...
</reviews>

Example JSON Return Data:

{"reviews": {
  "reviewData": [
    {"allowReviewersToJoin":true,
     ...
    }, ...]
  }
}



Get Reviews by Filter


URL:

GET /reviews-v1/filter/<filter>

Description:
Get all the reviews which match the given filter, for the current user.
Filter names are:

  • allReviews - All reviews for everyone.
  • allOpenReviews - Open reviews for everyone.
  • allClosedReviews - Closed reviews for everyone.
  • draftReviews - Draft reviews for everyone.
  • toReview - Reviews on which the current user is an uncompleted reviewer.
  • requireMyApproval - Reviews waiting to be approved by the current user.
  • toSummarize - Completed reviews which are ready for the current user to summarize.
  • outForReview - Reviews with uncompleted reviewers, on which the current reviewer is the moderator.
  • drafts - Draft reviews created by the current user.
  • open - Open reviews created by the current user.
  • closed - Closed reviews created by the current user.
  • trash - Abandoned reviews created by the current user.

Status Code:
200 (OK) on success.

Example XML Return Data:

<reviews>
  <reviewData>
    ...
  </reviewData>
  ...
</reviews>

Example JSON Return Data:

{"reviews": {
  "reviewData": [
    {"allowReviewersToJoin":true,
     ...
    }, ...]
  }
}



Get Reviews by Path


URL:

GET /reviews-v1/search/<repository>?path=<path>

Description:
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:
200 (OK) on success.

Example XML Return Data:

<reviews>
  <reviewData>
    ...
  </reviewData>
  ...
</reviews>

Example JSON Return Data:

{"reviews": {
  "reviewData": [
    {"allowReviewersToJoin":true,
     ...
    }, ...]
  }
}



Get Reviews through Custom Filter Criteria


URL:

GET /reviews-v1/filter?title=..&author=..&moderator=..&creator=..&reviewer=..&orRoles=true|false&complete=true|false&allReviewersComplete=true|false&project=..

Description:
Get all the reviews which match the specified filter criteria. Criteria are supplied as normal query parameters in the URL.
Filter criteria are:

  • title - Reviews whose title contain this substring.
  • author - Reviews authored by this user.
  • moderator - Reviews moderated by this user.
  • creator - Reviews created by this user.
  • reviewer - Reviews reviewed by this user.
  • orRoles - Whether to the value for author, creator, moderator and reviewer should be combined using OR (orRoles=true) or AND (orRoles=false).
  • complete - Reviews that the specified reviewer has completed.
  • allReviewersComplete - Reviews that all reviewers have completed.
  • project - Reviews for the specified project.

Status Code:
200 (OK) on success.

Example XML Return Data:

<reviews>
  <reviewData>
    ...
  </reviewData>
  ...
</reviews>

Example JSON Return Data:

{"reviews": {
  "reviewData": [
    {"allowReviewersToJoin":true,
     ...
    }, ...]
  }
}



Get Single Review Details


URL:

GET /reviews-v1/<id>/details

Description:
Get details of a single review.

Status Code:
200 (OK) on success.

Example XML Return Data:

<detailedReviewData>
  ...
</detailedReviewData>

Example JSON Return Data:

{"detailedReviewData": {
  "allowReviewersToJoin":false,
  ...
}}



Get Version Info


URL:

GET /reviews-v1/versionInfo

Description:
Returns the release number and build date of Crucible.

Status Code:
200 (OK) on success.

Example XML Return Data:

<versionInfo>
  <buildDate>2008-10-28</buildDate>
  <releaseNumber>1.6.3</releaseNumber>
</versionInfo>

Example JSON Return Data:

{"versionInfo":{"buildDate":"2008-10-28","releaseNumber":"1.6.3"}}



Document generated by Confluence on Jul 29, 2010 20:01