This document describes the comments resource.

A comment is something that a user records about a given app, file, or folder.

Comment Endpoints¶

Creating a comment¶

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.

Request¶

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.

Response¶

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.

Example¶

? 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."
  }
}

Listing comments¶

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.

Request¶

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.

Response¶

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.

Example¶

? 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."
    }
  ]
}

Retracting/Readmitting a comment¶

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.

Request¶

This endpoint requires a boolean retracted parameter.

Any body attached to the request will be ignored.

Response¶

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.

403¶

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.

Example¶

curl -X PATCH -H "$AUTH_HEADER" "localhost/secured/filesystem/f86700ac-df88-11e3-bf3b-6abdce5a08d5/comments/79a6a1f0-0745-21e3-c125-73dece2a6989?retracted=true"

Administratively deleting a comment¶

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.

Request¶

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.

Response¶

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.

Example¶

curl -X DELETE -H "$AUTH_HEADER" "localhost/admin/filesystem/entry/f86700ac-df88-11e3-bf3b-6abdce5a08d5/comments/79a6a1f0-0745-21e3-c125-73dece2a6989"