This document describes the comments resource.
A comment is something that a user records about a given app, file, or folder.
POST /apps/{app-id}/comments
Delegates to metadata: POST /apps/{app-id}/comments
POST /secured/filesystem/entry/{entry-id}/comments
Delegates to metadata: POST /filesystem/entry/{entry-id}/comments
This endpoint allows an authenticated user to post a comment on any app, accessible file, or accessible folder. {app-id} is the UUID of the app being commented on. {entry-id} is the UUID of the file or folder being commented on.
These endpoints forward requests to their corresponding metadata service endpoints. Please see the metadata documentation for more information.
A request to this endpoint requires no parameters. The user that owns the comment is determined from the authentication. Any query parameters will be ignored.
| Status Code | Cause |
|---|---|
| 201 | The comment was successfully posted |
| 400 | The request body wasn’t syntactically correct |
| 401 | Either the authentication header was not provided, or its value wasn’t correct. |
| 404 | From the /apps/{app-id}/comments endpoint, the app-id didn’t correspond to an existing app. From the /secured/filesystem/entry/{entry-id}/comments endpoint, entry-id didn’t correspond to an existing file or folder, or is not accessible by the user |
| 413 | The request body is too large |
Error responses may include a reason field, providing a short, human readable explanation of the failure.
? curl -X POST -H "$AUTH_HEADER" -d '{ "comment" : "That was interesting." }' localhost/secured/filesystem/entry/f86700ac-df88-11e3-bf3b-6abdce5a08d5/comments
{
"comment" : {
"id" : "68a6a1f0-f745-11e3-b125-73dece2a6978",
"commenter" : "tedgin",
"post_time" : 1403093431927,
"retracted" : false,
"comment" : "That was interesting."
}
}
GET /apps/{app-id}/comments
Delegates to metadata: GET /apps/{app-id}/comments
GET /secured/filesystem/entry/{entry-id}/comments
Delegates to metadata: GET /filesystem/entry/{entry-id}/comments
This endpoint allows an authenticated user to retrieve all of the comments made on an accessible file or folder, or any app. {app-id} is the UUID associated with the app. entry-id is the UUID associated with the file or folder.
These endpoints forward requests to their corresponding metadata service endpoints. Please see the metadata documentation for more information.
A request to this endpoint requires no parameters. The user that owns the comment is determined from the authentication. Any query parameters will be ignored.
Any attached request body will be ignored.
| Status Code | Cause |
|---|---|
| 200 | The list of comments will be in the response body |
| 401 | Either the authentication header was not provided, or its value wasn’t correct. |
| 404 | From the /apps/{app-id}/comments endpoint, the app-id didn’t correspond to an existing app. From the /secured/filesystem/entry/{entry-id}/comments endpoint, entry-id didn’t correspond to an existing file or folder, or is not accessible by the user |
Upon failure, a JSON document with a reason field will the returned. The reason field will provide a short, human readable explanation of the failure.
? curl -H "$AUTH_HEADER" localhost/secured/filesystem/entry/f86700ac-df88-11e3-bf3b-6abdce5a08d5/comments
{
"comments" : [
{
"id" : "68a6a1f0-f745-11e3-b125-73dece2a6978",
"commenter" : "tedgin",
"post_time" : 1403093431927,
"retracted" : false,
"comment" : "That was interesting."
},
{
"id" : "79a6a1f0-0745-21e3-c125-73dece2a6989",
"commenter" : "fool",
"post_time" : 1403093433001,
"retracted" : false,
"comment" : "No it wasn't."
}
]
}
PATCH /apps/{app-id}/comments/{comment-id}
PATCH /secured/filesystem/entry/{entry-id}/comments/{comment-id}
Delegates to metadata:
PATCH /apps/{app-id}/comments/{comment-id}
PATCH /admin/apps/{app-id}/comments/{comment-id}
PATCH /filesystem/entry/{entry-id}/comments/{comment-id}
PATCH /admin/filesystem/entry/{entry-id}/comments/{comment-id}
These endpoints allow an authenticated user to retract a given comment or to readmit a retracted comment on a given app, file, or folder. app-id is the UUID of the app. entry-id is the UUID of the file or folder. comment-id is the UUID of the comment.
These endpoints forward requests to their corresponding metadata service endpoints. In the case that the user is the owner of the app, file, or folder, then the request is forwarded to the corresponding metadata service /admin endpoint. Please see the metadata documentation for more information.
This endpoint requires a boolean retracted parameter.
Any body attached to the request will be ignored.
| Status Code | Cause |
|---|---|
| 200 | The comment corresponding to the comment-id UUID has been marked as retracted. |
| 400 | The retracted parameter was missing or had a value other than true or false. |
| 401 | Either the authentication header was not provided, or its value wasn’t correct. |
| 403 | See 403. |
| 404 | comment-id doesn’t exist, app-id doesn’t exist, or entry-id doesn’t exist or isn’t accessible by the user. |
| 409 | One of the query parameters was passed more than once with different values. |
Error responses may include a reason field, providing a short, human readable explanation of the failure.
When a comment is being retracted, a 403 will result if the app, file, or folder is not owned by the user and the comment was not created by the user. When a comment is being readmitted, a 403 will result if the comment wasn’t originally retracted by the user.
curl -X PATCH -H "$AUTH_HEADER" "localhost/secured/filesystem/f86700ac-df88-11e3-bf3b-6abdce5a08d5/comments/79a6a1f0-0745-21e3-c125-73dece2a6989?retracted=true"
DELETE /admin/apps/{app-id}/comments/{comment-id}
Delegates to metadata: DELETE /admin/apps/{app-id}/comments/{comment-id}
DELETE /admin/filesystem/entry/{entry-id}/comments/{comment-id}
Delegates to metadata: DELETE /admin/filesystem/entry/{entry-id}/comments/{comment-id}
This endpoint allows an administrative user to delete a given comment on a given app, file, or folder. comment-id is the UUID of the comment. app-id is the UUID of the app. entry-id is the UUID of the file or folder.
These endpoints forward requests to their corresponding metadata service endpoints. Please see the metadata documentation for more information.
A request to this endpoint requires no parameters. Any query parameters that are provided will be ignored.
Any body attached to the request will be ignored.
| Status Code | Cause |
|---|---|
| 200 | The comment corresponding to the comment-id UUID has been deleted. |
| 401 | Either the authentication header was not provided, or its value wasn’t correct. |
| 404 | Either the app corresponding to app-id doesn’t exist, the file or folder corresponding to entry-id doesn’t exist, or the comment corresponding to comment-id doesn’t. |
Error responses may include a reason field, providing a short, human readable explanation of the failure.
curl -X DELETE -H "$AUTH_HEADER" "localhost/admin/filesystem/entry/f86700ac-df88-11e3-bf3b-6abdce5a08d5/comments/79a6a1f0-0745-21e3-c125-73dece2a6989"