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.

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

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

Request to Create a New Review

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

{"detailedReviewData": {
  "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: