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 |
---|---|---|---|---|---|
|
A comment ID to seek to. Comments up to and including the specified ID are excluded from the results and do not count towards |
integer |
query |
No |
|
|
Maximum number of comments to return. This does not guarantee that |
integer |
query |
No |
100 |
|
Only comments for given topic are returned. Examples: |
string |
query |
No |
|
|
If a |
integer |
query |
No |
|
|
Prevents archived comments from being returned. (v5+) |
boolean |
query |
No |
|
|
Returns only comments that have been flagged as tasks. (v5+) |
boolean |
query |
No |
|
|
Limit the returned comments to ones that match the provided task state (one or more of |
array (of strings) |
query |
No |
|
|
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
}
lastSeen
can often be used as an offset for pagination, by using the value
in the after
parameter of subsequent requests.
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:
{
"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:
{
"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/
Description
Sends notification for comments
Parameters
Parameter | Description | Type | Parameter Type | Required |
---|---|---|---|---|
|
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. Examples: |
string |
query |
Yes |
Examples of successful responses
Successful Response:
HTTP/1.1 200 OK
{
"isValid": true,
"message": "Sending a notification for 3 comments",
"code": 200
}
When no comment notifications are found:
HTTP/1.1 200 OK
{
"isValid": true,
"message": "No comment notifications to send",
"code": 200
}
Sending notification for comments
To send all delayed comments:
curl -u "username:password" "https://my-swarm-host/api/v9/comments/notify\
?topic=reviews/911"
Swarm responds with a message detailing a notification sent with the number of comments it applied to.
{
"isValid": true,
"message": "No comment notifications to send",
"code": 200
}
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 to comment on. Examples: |
string |
form |
Yes |
|
|
Content of the comment. |
string |
form |
Yes |
|
|
If set to 'true' no notifications will ever be sent for this created comment |
string |
form |
No |
|
|
If set to 'true' notifications will be delayed |
string |
form |
No |
|
|
Optional task state of the comment. Valid values when adding a comment are |
string |
form |
No |
comment |
|
Optional flags on the comment. Typically set to |
array (of strings) |
form |
No |
|
|
File to comment on. Valid only for |
string |
form |
No |
|
|
Left-side diff line to attach the inline comment to. Valid only for |
integer |
form |
No |
|
|
Right-side diff line to attach the inline comment to. Valid only for |
integer |
form |
No |
|
|
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 |
|
|
With a |
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" \
-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:
{
"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" \
-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:
{
"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 of the comment to be edited |
integer |
path |
Yes |
|
Topic to comment on. Examples: |
string |
form |
No |
|
Content of the comment. |
string |
form |
Yes |
|
Optional task state of the comment. Note that certain transitions (such as moving from |
string |
form |
No |
|
Optional flags on the comment. Typically set to |
array (of strings) |
form |
No |
|
If set to 'true' no notifications will ever be sent for this edited comment |
string |
form |
No |
|
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:
{
"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:
{
"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": "comment",
"time": 123456789,
"topic": "reviews/2",
"updated": 123456790,
"user": "username"
}
}
Your search for returned result(s).