Crucible 2.0 : Crucible REST API Usage Example
This page last changed on Dec 08, 2008 by edawson.
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. AuthenticationRequests 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:
Retrieving ReviewsThis 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 StateIf 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 ReviewURLs 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 ReviewIf 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 ReviewTo 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> JSONAs 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.
Retrieving a Specific ReviewTo 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 RequestWhen 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 {"createReview": {"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 {"reviewData": { "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" }} |
![]() |
Document generated by Confluence on Jul 09, 2009 19:51 |