Crucible REST API Usage Example

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.

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.5 – the example won't 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 to jim: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.