Comments : Swarm Comments

Get List of Comments

GET /api/v9/comments/

Summary

Get List of Comments

Description

List comments.

Parameters

Parameter	Description	Type	Parameter Type	Required	Default Value
after	A comment ID to seek to. Comments up to and including the specified ID are excluded from the results and do not count towards max. Useful for pagination. Commonly set to the lastSeen property from a previous query.	integer	query	No
max	Maximum number of comments to return. This does not guarantee that max comments are returned. It does guarantee that the number of comments returned won’t exceed max.	integer	query	No	100
topic	Only comments for given topic are returned. Examples: reviews/1234, changes/1234 or jobs/job001234.	string	query	No
context[version]	If a reviews/1234 topic is provided, limit returned comments to a specific version of the provided review.	integer	query	No
ignoreArchived	Prevents archived comments from being returned. (v5+)	boolean	query	No
tasksOnly	Returns only comments that have been flagged as tasks. (v5+)	boolean	query	No
taskStates	Limit the returned comments to ones that match the provided task state (one or more of open, closed, verified, or comment). (v5+)	array (of strings)	query	No
fields	An optional comma-separated list (or array) of fields to show for each comment. Omitting this parameter or passing an empty value shows all fields.	string	query	No

Examples of successful responses

Successful Response:

HTTP/1.1 200 OK

{
  "topic": "",
  "comments": {
    "51": {
      "id": 51,
      "attachments": [],
      "body": "Short loin ground round sin reprehensible, venison west participle triple.",
      "context": [],
      "edited": null,
      "flags": [],
      "likes": [],
      "taskState": "comment",
      "time": 1461164347,
      "topic": "reviews/885",
      "updated": 1461164347,
      "user": "bruno"
    }
  },
  "lastSeen": 51
}

When no results are found, the comments array is empty:

HTTP/1.1 200 OK

{
  "topic": "jobs/job000011",
  "comments": [],
  "lastSeen": null
}

Examples of usage

Listing comments

To list comments:

curl -u "username:password" "https://my-swarm-host/api/v9/comments?topic=reviews/911&max=2&fields=id,body,time,user"

Swarm responds with a list of the first two comments for review 911 and a lastSeen value for pagination:

HTTP/1.1 200 OK

{
  "topic": "reviews/911",
  "comments": {
    "35": {
      "id": 35,
      "body": "Excitation thunder cats intelligent man braid organic bitters.",
      "time": 1461164347,
      "user": "bruno"
    },
    "39": {
      "id": 39,
      "body": "Chamber tote bag butcher, shirk truffle mode shabby chic single-origin coffee.",
      "time": 1461164347,
      "user": "swarm_user"
    }
  },
  "lastSeen": 39
}

Paginating a comment listing

To obtain the next page of a comments list (based on the previous example):

curl -u "username:password" "https://my-swarm-host/api/v9/comments?topic=reviews/911&max=2&fields=id,body,time,user&after=39"

Swarm responds with the second page of results, if any comments are present after the last seen comment:

HTTP/1.1 200 OK

{
  "topic": "reviews/911",
  "comments": {
    "260": {
      "id": 260,
      "body": "Reprehensible do lore flank ham hock.",
      "time": 1461164349,
      "user": "bruno"
    },
    "324": {
      "id": 324,
      "body": "Sinter lo-fi temporary, nihilist tote bag mustache swag consequence interest flexible.",
      "time": 1461164349,
      "user": "bruno"
    }
  },
  "lastSeen": 324
}

Send notification for comments

Summary

Sends notification for comments

POST /api/v9/comments/notify

Description

Sends notification for comments.

Parameters

Parameter	Description	Type	Parameter Type	Required
topic	This is going to send a single notification for any comments that were not notified immediately for the user authenticated for a given topic they are posting for. Example: reviews/1234.	string	form	Yes
preview	Set to true to check if there are comments waiting for a notification to be sent, the notification is not sent.	string	form	No

Examples of successful responses

Comment notification sent.

HTTP/1.1 200 OK

{
  "isValid": true,
  "message": "Sending a notification for 3 comments",
  "code": 200
}

No comments are waiting for a notification.

HTTP/1.1 200 OK

{
   "isValid": true,
   "message": "No comment notifications to send",
   "code": 200
}

Examples of usage

Sending notification for comments

To send a notification for all delayed comments:

curl -u "username:password" \
     -X POST \
     -d "topic=reviews/911" \
     "https://my-swarm-host/api/v9/comments/notify"

Swarm responds with a message detailing a notification sent with the number of comments it applied to.

HTTP/1.1 200 OK

{
  "isValid": true,
  "message": "Sending a notification for 3 comments",
  "code": 200
}

Checking to see if any comments are waiting for a notification to be sent

To check if there are any comments awaiting a notification without sending the notification, include "preview=true" in your request.

curl -u "username:password" \
     -X POST \
     -d "topic=reviews/911" \
     -d "preview=true" \
     "https://my-swarm-host/api/v9/comments/notify"

Swarm responds with a message without sending a notification.

HTTP/1.1 200 OK

{
  "isValid": true,
  "message": "Sending a notification for 3 comments",
  "code": 200
  "preview": true			
}

Add a Comment

Summary

Add a Comment

POST /api/v9/comments/

Description

Add a comment to a topic (such as a review or a job).

Parameters

Parameter	Description	Type	Parameter Type	Required	Default Value
topic	Topic to comment on. Examples: reviews/1234, changes/1234 or jobs/job001234.	string	form	Yes
body	Content of the comment.	string	form	Yes
silenceNotification	If set to 'true' no notifications will ever be sent for this created comment	string	form	No
delayNotification	If set to 'true' notifications will be delayed	string	form	No
taskState	Optional task state of the comment. Valid values when adding a comment are comment and open. This creates a plain comment or opens a task, respectively.	string	form	No	comment
flags[]	Optional flags on the comment. Typically set to closed to archive a comment.	array (of strings)	form	No
context[file]	File to comment on. Valid only for changes and reviews topics. Example: //depot/main/README.txt.	string	form	No
context[leftLine]	Left-side diff line to attach the inline comment to. Valid only for changes and reviews topics. If this is specified, context[file] must also be specified.	integer	form	No
context[rightLine]	Right-side diff line to attach the inline comment to. Valid only for changes and reviews topics. If this is specified, context[file] must also be specified.	integer	form	No
context[content]	Optionally provide content of the specified line and its four preceding lines. This is used to specify a short excerpt of context in case the lines being commented on change during the review. When not provided, Swarm makes an effort to build the content on its own - as this involves file operations, it could become slow.	array (of strings)	form	No
context[version]	With a reviews topic, this field specifies which version to attach the comment to.	integer	form	No

Example of response

Successful Response contains Comment entity:

HTTP/1.1 200 OK

{
  "comment": {
    "id": 42,
    "attachments": [],
    "body": "Best. Comment. EVER!",
    "context": [],
    "edited": null,
    "flags": [],
    "likes": [],
    "taskState": "comment",
    "time": 123456789,
    "topic": "reviews/2",
    "updated": 123456790,
    "user": "bruno"
  }
}

Examples of usage

Create a comment on a review

To create a comment on a review:

curl -u "username:password" \
     -X POST \
     -d "topic=reviews/2" \
     -d "body=This is my comment. It is an excellent comment. It contains a beginning, a middle, and an end." \
     "https://my-swarm-host/api/v9/comments"

JSON Response:

HTTP/1.1 200 OK

{
  "comment": {
    "id": 42,
    "attachments": [],
    "body": "This is my comment. It is an excellent comment. It contains a beginning, a middle, and an end.",
    "context": [],
    "edited": null,
    "flags": [],
    "likes": [],
    "taskState": "comment",
    "time": 123456789,
    "topic": "reviews/2",
    "updated": 123456790,
    "user": "username"
  }
}

Open a task on a review

To create a comment on a review, and flag it as an open task:

curl -u "username:password" \
     -X POST \
     -d "topic=reviews/2" \
     -d "taskState=open" \
     -d "body=If you could go ahead and attach a cover page to your TPS report, that would be great." \
     "https://my-swarm-host/api/v9/comments"

JSON Response:

HTTP/1.1 200 OK

{
  "comment": {
    "id": 43,
    "attachments": [],
    "body": "If you could go ahead and attach a cover page to your TPS report, that would be great.",
    "context": [],
    "edited": null,
    "flags": [],
    "likes": [],
    "taskState": "open",
    "time": 123456789,
    "topic": "reviews/2",
    "updated": 123456790,
    "user": "username"
  }
}

Edit a Comment

Summary

Edit a Comment

PATCH /api/v9/comments/{id}

Description

Edit a comment.

Parameters

Parameter	Description	Type	Parameter Type	Required
id	ID of the comment to be edited	integer	path	Yes
topic	Topic to comment on. Examples: reviews/1234, changes/1234 or jobs/job001234.	string	form	No
body	Content of the comment.	string	form	Yes
taskState	Optional task state of the comment. Note that certain transitions (such as moving from open to verified) are not possible without an intermediate step (addressed, in this case). Examples: comment (not a task), open, addressed, verified.	string	form	No
flags[]	Optional flags on the comment. Typically set to closed to archive a comment.	array (of strings)	form	No
silenceNotification	If set to 'true' no notifications will ever be sent for this edited comment	string	form	No
delayNotification	If set to 'true' notifications will be delayed	string	form	No

Example response

Successful Response contains Comment entity:

HTTP/1.1 200 OK

{
  "comment": {
    "id": 1,
    "attachments": [],
    "body": "Best. Comment. EVER!",
    "context": [],
    "edited": 123466790,
    "flags": [],
    "likes": [],
    "taskState": "comment",
    "time": 123456789,
    "topic": "reviews/42",
    "updated": 123456790,
    "user": "bruno"
  }
}

Examples of usage

Edit and archive a comment on a review

To edit and archive a comment on a review:

curl -u "username:password" \
     -X PATCH \
     -d "flags[]=closed" \
     -d "body=This comment wasn't as excellent as I may have lead you to believe. A thousand apologies." \
     "https://my-swarm-host/api/v9/comments/42"

JSON Response:

HTTP/1.1 200 OK

{
  "comment": {
    "id": 42,
    "attachments": [],
    "body": "This comment wasn't as excellent as I may have lead you to believe. A thousand apologies.",
    "context": [],
    "edited": 123466790,
    "flags": ["closed"],
    "likes": [],
    "taskState": "comment",
    "time": 123456789,
    "topic": "reviews/2",
    "updated": 123456790,
    "user": "username"
  }
}

Flag a task as addressed on a review

To flag an open task as addressed on a review:

curl -u "username:password" \
     -X PATCH \
     -d "taskState=addressed" \
     "https://my-swarm-host/api/v9/comments/43"

JSON Response:

HTTP/1.1 200 OK

{
  "comment": {
    "id": 43,
    "attachments": [],
    "body": "If you could go ahead and attach a cover page to your TPS report, that would be great.",
    "context": [],
    "edited": 123466790,
    "flags": ["closed"],
    "likes": [],
    "taskState": "addressed",
    "time": 123456789,
    "topic": "reviews/2",
    "updated": 123456790,
    "user": "username"
  }
}