Crucible 2.3 : Data Types
This page last changed on Nov 19, 2009 by edawson.
Definitions of data types used by the REST API. ReviewDataContains 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" }} ReviewItemDataDescribes 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. 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. DetailedReviewDataNote 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":""}} | ErrorWhen 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.
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 |