![]() | The content on this page is deprecated. Please see the separate documentation space for developer reference material about FishEye and Crucible. |
This page describes using the Crucible REST API to retrieve comments from reviews in Crucible. It's an overview of using the API, not a comprehensive reference.
The Crucible REST API provides a reference for all the REST operations supported by Crucible.
On this page:
The Crucible REST API lives under the URL http://HOSTNAME:PORT/CONTEXT/rest-service/
, where HOSTNAME:PORT
is the IP address and port of your FishEye instance and CONTEXT
is the web application context it is deployed under.
This page doesn't assume any particular REST client is being used – it just discusses the URLs to use and the responses which they will give. The information returned is in XML format.
This page assumes Crucible 1.6 – the examples (in particular JSON support) may not work with earlier versions.
Authentication
Requests to the REST API are simply HTTP requests, which can use any of the normal Crucible authentication methods. An unauthenticated request will execute as the anonymous user.
Authentication options are:
- The normal Crucible login cookie. A cookie named 'remember' in the request with the token returned by the REST authentication service on
http://HOSTNAME:PORT/rest-service/auth-v1/login?userName=jim&password=jimspassword
. This will return<?xml version="1.0" encoding="UTF-8" standalone="yes"?><loginResult><token>jim:2:4455f9a4387298a83aae6902e8843f89</token></loginResult>
. The value of the cookie should be set tojim:2:4455f9a4387298a83aae6902e8843f89
. - Trusted Applications. If Crucible trusts the application which is making the request, the user logged in to the trusted application will be authenticated in Crucible.
- Crowd. If Crucible is configured to use Crowd, then a request containing Crowd authentication will authenticate the Crowd user in Crucible.
- Basic Authentication. An RFC 2617 Basic Authentication header.
Retrieving Reviews
This example will use the reviews service, at the URL http://HOSTNAME:PORT/rest-service/reviews-v1
. A simple get on this URL will return every review in the system. The results will look like this:
<reviews> <reviewData> <author>pmcneil</author> <creator>pmcneil</creator> <description>14699: CRUC-230: allow links to be removed 14698: CRUC-230: don't allow linking cycles</description> <moderator>pmcneil</moderator> <name>CRUC-214: Generate comment/defect and open review report graphs</name> <permaId> <id>CR-FE-1</id> </permaId> <projectKey>CR-FE</projectKey> <repoName>FE</repoName> <state>Review</state> </reviewData> ... </reviews>
Retrieving Reviews in a Specific State
If you don't want to retrieve every review, you can specify a value for the state
parameter: http://HOSTNAME:PORT/rest-service/reviews-v1?state=Review,Summarize
to retrieve only those reviews in particular states.
The request only returns those reviews that the authenticated user is allowed to see.
Once you have the reviews you can use their permaId
to get more details, so: http://HOSTNAME:PORT/rest-service/reviews-v1/CR-FE-1
will return a single reviewData
element, identical to the one shown above.
Retrieving Comments From a Review
URLs like http://HOSTNAME:PORT/rest-service/reviews-v1/CR-FE-1/thing
will return information about thing
records belonging to the review.
So http://HOSTNAME:PORT/rest-service/reviews-v1/CR-FE-1/comments
returns all the comments in the review:
<comments> <versionedComment> <createDate>2008-03-03T22:22:00.920+11:00</createDate> <defectApproved>false</defectApproved> <defectRaised>false</defectRaised> <deleted>false</deleted> <draft>false</draft> <message>why use roll instead of add??</message> <permaId> <id>CMT:200</id> </permaId> <reviewItemId> <id>CFR-281</id> </reviewItemId> <user>mquail</user> <fromLineRange>196-199, 230-233</fromLineRange> <toLineRange>206-209, 240-251</toLineRange> </versionedComment> ... more versioned comments ... <generalComment> <createDate>2008-03-25T17:15:20.380+11:00</createDate> <defectApproved>false</defectApproved> <defectRaised>true</defectRaised> <deleted>false</deleted> <draft>false</draft> <message>when there are no comments in the last week the vertical axis shows -5 as the starting point</message> <user>pmcneil</user> </generalComment> ... more general comments ... </comments>
Retrieving Properties of a File Under Review
If you need more information about the file a versioned comment was on, the URL http://HOSTNAME:PORT/rest-service/reviews-v1/CR-FE-1/reviewitems/CFR-281
gives more details:
<fisheyeReviewItemData> <permId> <id>CFR-281</id> </permId> <fromPath></fromPath> <fromRevision></fromRevision> <repositoryName>FE</repositoryName> <toPath>branches/iteration03/src/java/com/cenqua/crucible/reports/CommentsDefects/CommentDatasetMaker.java</toPath> <toRevision>13947</toRevision> </fisheyeReviewItemData>
That particular review item is a new file, so the fromPath
and fromRevision
elements are empty.
Creating a New Review
To create a review, do a POST call to the reviews url (http://HOSTNAME:PORT/rest-service/reviews-v1
) with the following XML document as request body (note that you need to be authenticated be be able to create a new review, so use Basic HTTP authentication for this call):
<?xml version="1.0"?> <createReview> <reviewData> <author> <!-- required element --> <userName>joe</userName> </author> <creator> <!-- required element --> <userName>fred</userName> </creator> <moderator> <!-- required element --> <userName>erik</userName> </moderator> <description>These is the Statement of Objectives.</description> <name>Title of the new review</name> <!-- required element --> <projectKey>CR</projectKey> <!-- required element --> <allowReviewersToJoin>true</allowReviewersToJoin> </reviewData> </createReview>
JSON
As of Crucible 1.6.3, JSON serialization is supported for REST requests and responses. Using the Accept
request header, clients can specifiy whether the response document should be encoded in XML or JSON. Unless specified differently, Crucible will respond using XML and will interpret requests as XML. Crucible will always include the Content-Type
header in the response to identify the encoding. Likewise, when a client sends a JSON request document, it must use the Content-Type: application/json
header. It is possible to use a different encoding for the request and the response.
![]() | Note JSON support is currently experimental. |
Retrieving a Specific Review
To retrieve the contents of a specific review as a JSON document, rather than XML, include the Accept: application/json
header in your HTTP request. The example below includes the HTTP headers of both the request and the response to illustrate this:
Request:
GET /rest-service/reviews-v1/CR-3/details HTTP/1.1 Host: localhost:8060 Authorization: Basic am9lOmpvZQ== Accept: application/json
Response:
HTTP/1.1 200 OK Cache-Control: private Content-Type: application/json Last-Modified: Sun, 26 Oct 2008 23:05:45 GMT ETag: "1225062345005-140" { "allowReviewersToJoin":false, "author":{"displayName":"Joe","userName":"joe"}, "createDate":"2008-10-27T09:50:05.064+1100", "creator":{"displayName":"Joe","userName":"joe"}, "description":"", "metricsVersion":1, "moderator":{"displayName":"Joe","userName":"joe"}, "name":"readme ", "permaId":{"id":"CR-3"}, "projectKey":"CR", "state":"Draft", "actions": { "actionData":[{"name":"action:deleteReview"},{"name":"action:rejectReview"},{"name":"action:abandonReview"},{"name":"action:summarizeReview"}, {"name":"action:modifyReviewFiles"},{"name":"action:approveReview"},{"name":"action:recoverReview"},{"name":"action:commentOnReview"}, {"name":"action:submitReview"},{"name":"action:createReview"},{"name":"action:viewReview"},{"name":"action:reopenReview"},"name":"action:closeReview"}] }, "generalComments":"", "reviewItems":"", "reviewers":"", "transitions": { "transitionData":[{"name":"action:approveReview"},{"name":"action:abandonReview"}] }, "versionedComments":"" }
Note that the response document above has been indented to increase readability in this example.
Making a JSON Request
When sending a request document using JSON, include the Content-Type: application/json
header in the HTTP request. The example below creates a new review using JSON. Again, the relevant HTTP request and response headers are included:
Request:
POST /rest-service/reviews-v1 HTTP/1.1 Host: localhost:8060 Content-Length: 269 Authorization: Basic am9lOmpvZQ== Accept: application/json Content-Type: application/json { {"reviewData": { "allowReviewersToJoin":false, "author":{"userName":"joe"}, "creator":{"userName":"joe"}, "moderator":{"userName":"matt"}, "description":"JSON Test Review", "metricsVersion":1, "name":"readme ", "projectKey":"CR" } }
Response:
HTTP/1.1 201 Created Content-Type: application/json Location: http://localhost:8060/rest-service/reviews-v1/CR-12 { "allowReviewersToJoin":false, "author":{"displayName":"joe lowercase","userName":"joe"}, "createDate":"2008-10-27T17:21:29.779+1100", "creator":{"displayName":"joe lowercase","userName":"joe"}, "description":"JSON Test Review", "metricsVersion":1, "moderator":{"displayName":"Matt Quail","userName":"matt"}, "name":"readme ", "permaId":{"id":"CR-12"}, "projectKey":"CR", "state":"Draft" }