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.

Definitions of data types used by the REST API.

ReviewData

Contains basic information about a review.

Sample XML:

<reviewData>
  <allowReviewersToJoin>false</allowReviewersToJoin>
  <author>
    <displayName>Matt Quail</displayName>
    <userName>matt</userName>
  </author>
  <createDate>2008-08-25T12:38:14.603+1000</createDate>
  <creator>
    <displayName>Matt Quail</displayName>
    <userName>matt</userName>
  </creator>
  <description>Review things and stuff</description>
  <metricsVersion>1</metricsVersion>
  <moderator>
    <displayName>Matt Quail</displayName>
    <userName>matt</userName>
  </moderator>
  <name>Test review 1</name><permaId>
  <id>CR-1</id></permaId>
  <projectKey>CR</projectKey>
  <state>Review</state>
</reviewData>

Sample JSON:

{"reviewData": {
	"allowReviewersToJoin":false,
	"author":{"displayName":"Matt Quail","userName":"matt"},
	"createDate":"2008-10-27T09:50:05.064+1100",
	"creator":{"displayName":"Matt Quail","userName":"matt"},
	"moderator":{"displayName":"Matt Quail","userName":"matt"},
	"description":"Review things and stuff",
	"metricsVersion":1,
	"name":"Test review 1",
	"permaId":{"id":"CR-3"},
	"projectKey":"CR",
	"state":"Draft"
}}

ReviewItemData

Describes a single item that is under review. An item can represent the changes between two or more revisions of a file in a source repository, a change that was uploaded to Crucible as a unified diff or patch file, or it can represent any arbitrary file uploaded and attached to a review. Below are three examples of reviewItemData in XML, followed by the same three in JSON:

Sample XML:

  <!-- ReviewItemData representing a changes between two revisions: -->
  <reviewItem expand="revisions">
    <permId>
      <id>CFR-40</id>
    </permId>
    <authorName>evzijst</authorName>
    <commitDate>2008-10-14T15:25:08.755+1000</commitDate>
    <commitType>Modified</commitType>
    <fileType>File</fileType>
    <fromContentUrl>/cru/CR-4/rawcontent/89/test2%2Ftrunk%2Fsrc%2Fmain%2Fjava%2Fcom%2Fatlassian%2FTest.java</fromContentUrl>
    <fromPath>test2/trunk/src/main/java/com/atlassian/Test.java</fromPath>
    <fromRevision>9</fromRevision>
    <repositoryName>Local</repositoryName>
    <toContentUrl>/cru/CR-4/rawcontent/80/test2%2Ftrunk%2Fsrc%2Fmain%2Fjava%2Fcom%2Fatlassian%2FTest.java</toContentUrl>
    <toPath>test2/trunk/src/main/java/com/atlassian/Test.java</toPath>
    <toRevision>10</toRevision>
    <revisions size="4"/>
  </reviewItem>

  <!-- ReviewItemData representing a file from an uploaded unified diff: -->
  <reviewItem expand="revisions">
    <permId>
      <id>CFR-38</id>
    </permId>
    <authorName>joe</authorName>
    <commitDate>2008-11-19T15:45:57.953+1100</commitDate>
    <commitType>Modified</commitType>
    <fileType>File</fileType>
    <fromPath>src/java/com/atlassian/crucible/spi/rpc/AbstractJAXBContextResolver.java</fromPath>
    <fromRevision>2:F</fromRevision>
    <patchUrl>/cru/CR-4/downloadPatch/4/CRUC-582.patch</patchUrl>
    <repositoryName>PATCH:4</repositoryName>
    <toPath>src/java/com/atlassian/crucible/spi/rpc/AbstractJAXBContextResolver.java</toPath>
    <toRevision>2:T</toRevision>
    <revisions size="2"/>
  </reviewItem>

  <!-- ReviewItemData representing an uploaded binary file: -->
  <reviewItem expand="revisions">
    <permId>
      <id>CFR-31</id>
    </permId>
    <authorName>joe</authorName>
    <commitDate>2008-11-13T10:15:05.510+1100</commitDate>
    <commitType>Added</commitType>
    <fileType>File</fileType>
    <fromPath/>
    <fromRevision/>
    <repositoryName>UPLOAD:4</repositoryName>
    <toContentUrl>/cru/CR-4/rawcontent/52/scm-plugin.tgz</toContentUrl>
    <toPath>jackrabbit-scm-plugin.tgz</toPath>
    <toRevision>34</toRevision>
    <revisions size="1"/>
  </reviewItem>

Sample JSON

{"reviewItem":
	{"@expand":"revisions",
	"permId":{"id":"CFR-40"},
	"authorName":"evzijst",
	"commitDate":"2008-10-14T15:25:08.755+1000",
	"commitType":"Modified",
	"fileType":"File",
	"fromContentUrl":"\/cru\/CR-4\/rawcontent\/89\/test2%2Ftrunk%2Fsrc%2Fmain%2Fjava%2Fcom%2Fatlassian%2FTest.java",
	"fromPath":"test2\/trunk\/src\/main\/java\/com\/atlassian\/Test.java",
	"fromRevision":9,
	"repositoryName":"Local",
	"toContentUrl":"\/cru\/CR-4\/rawcontent\/80\/test2%2Ftrunk%2Fsrc%2Fmain%2Fjava%2Fcom%2Fatlassian%2FTest.java",
	"toPath":"test2\/trunk\/src\/main\/java\/com\/atlassian\/Test.java",
	"toRevision":10,
	"revisions":{"@size":"4"}}
}

{"reviewItem":
	{"@expand":"revisions",
	"permId":{"id":"CFR-38"},
	"authorName":"joe",
	"commitDate":"2008-11-19T15:45:57.953+1100",
	"commitType":"Modified",
	"fileType":"File",
	"fromPath":"src\/java\/com\/atlassian\/crucible\/spi\/rpc\/AbstractJAXBContextResolver.java",
	"fromRevision":"2:F",
	"patchUrl":"\/cru\/CR-4\/downloadPatch\/4\/CRUC-582.patch",
	"repositoryName":"PATCH:4",
	"toPath":"src\/java\/com\/atlassian\/crucible\/spi\/rpc\/AbstractJAXBContextResolver.java",
	"toRevision":"2:T",
	"revisions":{"@size":"2"}}
}

{"reviewItem":
	{"@expand":"revisions",
	"permId": {"id":"CFR-31"},
	"authorName":"joe",
	"commitDate":"2008-11-13T10:15:05.510+1100",
	"commitType":"Added",
	"fileType":"File",
	"fromPath":"",
	"fromRevision":"",
	"repositoryName":"UPLOAD:4",
	"toContentUrl":"\/cru\/CR-4\/rawcontent\/52\/jackrabbit-scm-plugin.tgz",
	"toPath":"jackrabbit-scm-plugin.tgz",
	"toRevision":34,
	"revisions":{"@size":"1"}}
}

The above section contains three reviewItemData instances that illustrate the use of the individual elements. The main elements are the <to../> and <from../> elements. These describe the two revisions of a review item where the to.. is the most recent and from.. the oldest revision of the item that is under review.

When using Iterative Reviewing, an item can contains more than two file revisions. The <revisions/> element contains information on every revision under review, while <to../> and <from../> always point to the first and the last revisions (the cumulative changes). By default, the <revisions/> element is collapsed and contains the size= attribute that indicates the total number of file revisions in the review item. To expand this list, use the ?append=revisions url parameter, e.g.:

http://localhost:6060/crucible/rest-service/reviews-v1/CR-FE-2033/reviewitems/CFR-23489?expand=revisions

Note that when a new file is added, it will not have the from.. elements and likewise, when a file gets removed, it will lack the to.. elements.
The <to../> and <from../> elements also include urls that point to the file contents hosted in Crucible. These are the <fromContentUrl/> and <toContentUrl/> elements. These are relative URLs that come after the web application context, so for example to download the file from the third reviewItemData, access: http://HOSTNAME:PORT/CONTEXT/cru/CR-4/rawcontent/52/scm-plugin.tgz.

Note that <fromContentUrl/> and <toContentUrl/> only apply to either uploaded files or revisions on files in one of the Crucible repositories. Uploaded patch files lack these elements because a unified diff file usually only contains the sections of two files that were changed, but not the code that was unchanged. As a result, Crucible is unable to provide links for the individual files. Instead, the <patchUrl/> element contains a relative link to the original patch file that was uploaded by the creator of the review.

DetailedReviewData

Note that the reviewItems element is empty when multiple reviews are retrieved via REST. To include the reviewItems in a detailedReviewData structure you must retrieve a single review via the URL /rest-service/reviews-v1/<review id>/details.

Sample XML:

<detailedReviewData>
	<allowReviewersToJoin>false</allowReviewersToJoin>
	<author>
		<displayName>Matt Quail</displayName>
		<userName>matt</userName>
	</author>
	<createDate>2008-09-16T10:50:26.862+1000</createDate>
	<creator>
		<displayName>Matt Quail</displayName>
		<userName>matt</userName>
	</creator>
	<description/>
	<metricsVersion>1</metricsVersion>
	<moderator>
		<displayName>Matt Quail</displayName>
		<userName>matt</userName>
	</moderator>
	<name/>
	<permaId>
		<id>CR-1</id>
	</permaId>
	<projectKey>CR</projectKey>
	<state>Draft</state>
	<actions>
		<actionData>
			<name>action:abandonReview</name>
		</actionData>
		<actionData>
			<name>action:closeReview</name>
		</actionData>
		<actionData>
			<name>action:submitReview</name>
		</actionData>
		<actionData>
			<name>action:reopenReview</name>
		</actionData>
		<actionData>
			<name>action:summarizeReview</name>
		</actionData>
		<actionData>
			<name>action:rejectReview</name>
		</actionData>
		<actionData>
			<name>action:deleteReview</name>
		</actionData>
		<actionData>
			<name>action:approveReview</name>
		</actionData>
		<actionData>
			<name>action:modifyReviewFiles</name>
		</actionData>
		<actionData>
			<name>action:viewReview</name>
		</actionData>
		<actionData>
			<name>action:commentOnReview</name>
		</actionData>
		<actionData>
			<name>action:recoverReview</name>
		</actionData>
		<actionData>
			<name>action:createReview</name>
		</actionData>
	</actions>
	<generalComments/>
	<reviewItems>
		<reviewItem>
			<permId>
				<id>CFR-1</id>
			</permId>
			<authorName>admin</authorName>
			<commitDate>2008-08-27T10:19:17.000+1000</commitDate>
			<commitType>Modified</commitType>
			<fileType>File</fileType>
			<fromPath>ds/Home</fromPath>
			<fromRevision>1</fromRevision>
			<repositoryName>localhost</repositoryName>
			<toPath>ds/Home</toPath>
			<toRevision>2</toRevision>
		</reviewItem>
		<reviewItem>
			<permId>
				<id>CFR-2</id>
			</permId>
			<authorName>tomd</authorName>
			<commitDate>2008-09-09T16:42:28.786+1000</commitDate>
			<commitType>Added</commitType>
			<fileType>File</fileType>
			<fromPath/>
			<fromRevision/>
			<repositoryName>mylocalsvn</repositoryName>
			<toPath>aaa/bbb/qqq.txt</toPath>
			<toRevision>3</toRevision>
		</reviewItem>
	</reviewItems>
	<reviewers/>
	<transitions>
		<transitionData>
			<name>action:approveReview</name>
		</transitionData>
		<transitionData>
			<name>action:abandonReview</name>
		</transitionData>
	</transitions>
	<versionedComments/>
</detailedReviewData>

Sample JSON:

{"detailedReviewData": {
	"allowReviewersToJoin":false,
	"author":{"displayName":"joe lowercase","userName":"joe"},
	"createDate":"2008-10-27T09:50:05.064+1100",
	"creator":{"displayName":"joe lowercase","userName":"joe"},
	"description":"",
	"metricsVersion":1,
	"moderator":{"displayName":"joe lowercase","userName":"joe"},
	"name":"readme ",
	"permaId":{"id":"CR-3"},
	"projectKey":"CR",
	"state":"Draft",
	"actions": {
		"actionData":[{"name":"action:rejectReview"},{"name":"action:closeReview"},
		{"name":"action:modifyReviewFiles"},{"name":"action:abandonReview"},
		{"name":"action:commentOnReview"},{"name":"action:reopenReview"},
		{"name":"action:createReview"},{"name":"action:recoverReview"},
		{"name":"action:deleteReview"},{"name":"action:approveReview"},
		{"name":"action:viewReview"},{"name":"action:submitReview"},
		{"name":"action:summarizeReview"}]
	},
	"generalComments":"",
	"reviewItems": {"reviewItem":[
		{"permId":{"id":"CFR-1"},
		"authorName":"evzijst",
		"commitDate":"2008-10-14T15:25:08.755+1000",
		"commitType":"Modified",
		"fileType":"File",
		"fromPath":"test2\/trunk\/src\/main\/java\/com\/atlassian\/Test.java",
		"fromRevision":9,
		"repositoryName":"Local",
		"toPath":"test2\/trunk\/src\/main\/java\/com\/atlassian\/Test.java",
		"toRevision":10},
		{"permId":{"id":"CFR-2"},
		"authorName":"evzijst",
		"commitDate":"2008-10-14T15:25:08.755+1000",
		"commitType":"Added",
		"fileType":"Directory",
		"fromPath":"",
		"fromRevision":"",
		"repositoryName":"Local",
		"toPath":"test2\/trunk\/src\/test\/java\/com",
		"toRevision":10}]
	},
	"reviewers":"",
	"transitions":{"transitionData":[
		{"name":"action:approveReview"},
		{"name":"action:abandonReview"}]
	},
	"versionedComments":""}}

|

Error

When a request cannot be serviced properly due to either a server-side problem, or invalid client input, Crucible will return an error document, combined with an HTTP status code other than 200. This XML document contains a number of elements that describe the problem. Note that the HTTP status code distinguishes between client- and server-side causes.
Below is the error that is returned when asking for a non existent resource. The status code for this response is 404 "Document Not Found". Other possible status codes for error responses include 400 "Bad Request" (for example when a request contains an invalid POST body) and 403 "Forbidden" (when accessing a resource without permission).

Sample XML:

<error>
	<code>NotFound</code>
	<message>Unknown metrics version: 45</message>
	<stacktrace>com.atlassian.crucible.spi.services.NotFoundException: Unknown metrics version: 45
	at com.atlassian.crucible.spi.impl.DefaultReviewService.getMetrics(DefaultReviewService.java:689)
	at com.atlassian.crucible.spi.rpc.RestReviewService$22.doGet(RestReviewService.java:645)
	at com.atlassian.crucible.spi.rpc.RestReviewService$22.doGet(RestReviewService.java:644)
	at com.atlassian.crucible.spi.rpc.ConditionalGet.doConditionalGet(ConditionalGet.java:46)
	at com.atlassian.crucible.spi.rpc.RestReviewService.getMetrics(RestReviewService.java:643)
	...
	</stacktrace>
</error>

Sample JSON:

{
	"code":"NotFound",
	"message":"No review exists with permId 'CR-333'",
	"stacktrace":"com.atlassian.crucible.spi.services.NotFoundException: Unknown metrics version: 45
	at com.atlassian.crucible.spi.impl.DefaultReviewService.getMetrics(DefaultReviewService.java:689)
	at com.atlassian.crucible.spi.rpc.RestReviewService$22.doGet(RestReviewService.java:645)
	at com.atlassian.crucible.spi.rpc.RestReviewService$22.doGet(RestReviewService.java:644)
	at com.atlassian.crucible.spi.rpc.ConditionalGet.doConditionalGet(ConditionalGet.java:46)
	at com.atlassian.crucible.spi.rpc.RestReviewService.getMetrics(RestReviewService.java:643)
	..."
}
Document generated by Confluence on Jul 29, 2010 20:01