This page last changed on Jun 29, 2009 by rosie@atlassian.com.

On this page:

Comments

Add a Reply to a Comment

URL:

POST /reviews-v1/<review id>/comments/<comment id>/replies

Description:
Add a reply to an existing comment.

The POST data is a generalCommentData structure.
Status Code:
201 (Created) on success. The response will contain the Location response header with the URL of the newly created resource.

Add Comment to a Review Item

URL:

POST /reviews-v1/<review id>/reviewitems/<review item id>/comments

Description:
Add a comment to a review. Returns the completed versionedLineCommentData structure.

The POST data is a versionedLineCommentData structure.
Status Code:
201 (Created) on success. The response will contain the Location response header with the URL of the newly created resource.

Add General Comment to a Review

URL:

POST /reviews-v1/<review id>/comments

Description:
Add a general comment to a review. Returns the completed generalCommentData structure.

The POST data is a generalCommentData structure.
Status Code:
201 (Created) on success. The response will contain the Location response header with the URL of the newly created resource.

Delete a Comment

URL:

DELETE /reviews-v1/<review id>/comments/<comment id>

Description:
Remove an existing comment.
Status Code:
204 (No Content) on success.

Delete a Reply

URL:

DELETE /reviews-v1/<review id>/comments/<comment id>/replies/<reply id>

Description:
Delete a reply.
Status Code:
204 (No Content) on success.

Get a Comment

URL:

GET /reviews-v1/<review id>/comments/<comment id>

Description:
Retrieve an existing comment
Status Code:
200 (OK) on success.

Comment Read Status:
This attribute details the read status of the comment for the particular user that the request has been made for. There are three possible values:

  • UNREAD: The comment has not been read.
  • READ: The comment has been viewed.
  • LEAVE_UNREAD: The comment has been read but marked by the user to be left for later referral.

Anonymous access requests and users who do not have permission to comment on a review always return the READ value.

Example XML Return Data:

<comments>
	<versionedLineCommentData>
		...
	</versionedLineCommentData>
</comments>

Example JSON Return Data:

{"comments": [
	{"versionedCommentData": ...}
]}



Get Comments on a Review Item

URL:

GET /reviews-v1/<review id>/reviewitems/<review item id>/comments

Description:
Get all the comments made on a review item.
Status Code:
200 (OK) on success.

Example XML Return Data:

<comments>
	<versionedLineCommentData>
		...
	</versionedLineCommentData>
	...
</comments>

Example JSON Return Data:

{"comments": [
	{"versionedCommentData": ...}
	{"versionedCommentData": ...}
]}



Get Comments on Files

URL:

GET /reviews-v1/<review id>/comments/versioned

Description:
Get all the versioned comments made on a review – that is, comments which are on a particular file in the review.
Status Code:
200 (OK) on success.

Example XML Return Data:

<comments>
	<versionedLineCommentData>
		...
	</versionedLineCommentData>
	...
</comments>

Example JSON Return Data:

{"comments": [
	{"versionedCommentData": ...}
	{"versionedCommentData": ...}
]}



Get General Comments

URL:

GET /reviews-v1/<review id>/comments/general

Description:
Get all the general comments made on a review – that is, comments which are not attached to a particular file in the review.
Status Code:
200 (OK) on success.

Example XML Return Data:

<comments>
	<generalCommentData>
		...
	</generalCommentData>
</comments>

Example JSON Return Data:

{"comments": [
	{"generalCommentData":{"createDate":"2008-10-30T16:32:51.032+1100",
	"defectApproved":false,
	"defectRaised":true,
	"deleted":false,
	"draft":false,
        "readStatus":"UNREAD",
	"message":"A general comment.",
	"metrics":[
		{"entry":{"key":"classification","value":[{"configVersion":1},"Not conforming to standards"]}},
		{"entry":{"key":"rank","value":[{"configVersion":1},"Minor"]}}],
	"permaIdAsString":"CMT:1",
	"replies":"",
	"user":{"displayName":"joe lowercase","userName":"joe"},"permId":{"id":"CMT:1"}},
	{"generalCommentData":{"createDate":"2008-11-03T10:26:50.951+1100",
	"defectApproved":false,
	"defectRaised":false,
	"deleted":false,
	"draft":false,
	"message":"Another general comment.",
	"metrics":"",
	"permaIdAsString":"CMT:4",
	"replies":"",
	"user":{"displayName":"joe lowercase","userName":"joe"},
	"permId":{"id":"CMT:4"}}
]}



Get Review Comments

URL:

GET /reviews-v1/<review id>/comments

Description:
Get all the comments made on a review. The versionedLineCommentData tag may contain fromLineRange and toLineRange tags, indicating that the comment was made against a specific range of lines.
Status Code:
200 (OK) on success.

Example XML Return Data:

<comments>
	<generalCommentData>
		<createDate>2008-09-16T16:28:02.833+1000</createDate>
		<defectApproved>false</defectApproved>
		<defectRaised>false</defectRaised>
		<deleted>false</deleted>
		<draft>false</draft>
                <readStatus>READ</readStatus>
		<message>This is a general comment.</message>
		<metrics/>
		<permaIdAsString>CMT:1</permaIdAsString>
		<replies/>
		<user>
			<displayName>Matt Quail</displayName>
			<userName>matt</userName>
		</user>
		<permId>
			<id>CMT:1</id>
		</permId>
	</generalCommentData>
	<versionedLineCommentData>
		<createDate>2008-09-16T16:28:26.432+1000</createDate>
		<defectApproved>false</defectApproved>
		<defectRaised>true</defectRaised>
		<deleted>false</deleted>
		<draft>false</draft>
                <readStatus>LEAVE_READ</readStatus>
		<message>This is a revision level defect.</message>
		<metrics>
			<entry>
				<key>classification</key>
				<value>
					<configVersion>1</configVersion>
					<value>Inconsistent</value>
				</value>
			</entry>
			<entry>
				<key>rank</key>
				<value>
					<configVersion>1</configVersion>
					<value>Major</value>
				</value>
			</entry>
		</metrics>
		<permaIdAsString>CMT:2</permaIdAsString>
		<replies/>
		<user>
			<displayName>Matt Quail</displayName>
			<userName>matt</userName>
		</user>
		<permaId>
			<id>CMT:2</id>
		</permaId>
		<reviewItemId>
			<id>CFR-4</id>
		</reviewItemId>
	</versionedLineCommentData>
	<versionedLineCommentData>
		<createDate>2008-09-16T16:28:54.604+1000</createDate>
		<defectApproved>false</defectApproved>
		<defectRaised>false</defectRaised>
		<deleted>false</deleted>
		<draft>false</draft>
                <readStatus>UNREAD</readStatus>
		<message>This is a comment covering two lines of a revision.</message>
		<metrics/>
		<permaIdAsString>CMT:3</permaIdAsString>
		<replies/>
		<user>
			<displayName>Matt Quail</displayName>
			<userName>matt</userName>
		</user>
		<permaId>
			<id>CMT:3</id>
		</permaId>
		<reviewItemId>
			<id>CFR-4</id>
		</reviewItemId>
		<fromLineRange>2-3</fromLineRange>
		<toLineRange>3-4</toLineRange>
	</versionedLineCommentData>
</comments>

Example JSON Return Data:

{"comments": {
	"generalCommentData":{
	"createDate":"2008-10-30T16:32:51.032+1100",
	"defectApproved":false,
	"defectRaised":true,
	"deleted":false,
	"draft":false,
        "readStatus":"READ",
	"message":"A general comment.",
	"metrics": [
		"entry":{"key":"classification","value":{"configVersion":1},"Not conforming to standards"},
		entry":{"key":"rank","value":{"configVersion":1},"Minor"}],
	"permaIdAsString":"CMT:1",
	"replies":"",
	"user":{"displayName":"joe lowercase","userName":"joe"},
	"permId":{"id":"CMT:1"},
	"versionedLineCommentData": [
		{"createDate":"2008-10-30T16:33:02.726+1100",
		"defectApproved":false,
		"defectRaised":false,
		"deleted":false,
		"draft":false,
                "readStatus":"LEAVE_READ",
		"message":"This is wrong",
		"metrics":"",
		"permaIdAsString":"CMT:2",
		"replies":"",
		"user":{"displayName":"joe lowercase","userName":"joe"},
		"permaId":{"id":"CMT:2"},
		"reviewItemId":{"id":"CFR-4"},
		"toLineRange":"1-2"},
	{"createDate":"2008-10-30T16:34:12.535+1100",
		"defectApproved":false,
		"defectRaised":false,
		"deleted":false,
		"draft":false,
                "readStatus":"UNREAD",
		"message":"This is a revision level defect.",
		"metrics":"",
		"permaIdAsString":"CMT:3",
		"replies":"",
		"user":{"displayName":"joe lowercase","userName":"joe"},
		"permaId":{"id":"CMT:3"},
		"reviewItemId":{"id":"CFR-5"}}
]}



Mark a Comment as Read

URL:

POST /reviews-v1/<review id>/comments/<comment id>/markAsRead

Description:
Marks a particular comment as read.

Status Code:
200 (OK) on success.

Mark a Comment as Leave Unread

URL:

POST /reviews-v1/<review id>/comments/<comment id>/markAsLeaveUnread

Description:
Marks a particular comment as leave unread.

Status Code:
200 (OK) on success.

Mark all Comments as Read

URL:

POST /reviews-v1/<review id>/comments/markAllAsRead

Description:
Marks all comments in the review which are in an unread state as read. Any comments which are in the leave unread state are not modified.

Status Code:
200 (OK) on success.

Get the Replies to a Comment

URL:

GET /reviews-v1/<review id>/comments/<comment id>/replies

Description:
Get the replies to an existing comment.
Status Code:
200 (OK) on success.

Example XML Return Data:

<comments>
	<generalCommentData>
		...
	</generalCommentData>
	...
</comments>

Example JSON Return Data:

{"comments": [
	{"generalCommentData": ...}
	{"generalCommentData": ...}
]}



Publish a Draft Comment

POST /reviews-v1/<review id>/publish/<comment id>

Description:
Publish a draft comments on the review.
Status Code:
200 (OK) on success.

Publish All Draft Comments

POST /reviews-v1/<review id>/publish

Description:
Publish all the user's draft comments on the review.
Status Code:
200 (OK) on success.

Update a Comment

URL:

POST /reviews-v1/<review id>/comments/<comment id>

Description:
Update an existing comment. The readStatus attribute is ignored when updating a comment.

The POST data is a generalCommentData structure.
Status Code:
200 (OK) on success.

Document generated by Confluence on Jul 09, 2009 19:51