The Comment Resource

From Ocean Framework Documentation Wiki
Jump to: navigation, search

The Comment resource has one public URL. (For information about the difference between Public and Internal URLs and HATEOAS conventions, please see API Structure and Conventions.)

/v1/comments

Structure

body
(String) The body of the Note. Required.
created_at
(String) A datetime string in GMT.
updated_at
(String) A datetime string in GMT.
{
 "comment": {
          "_links": {
            "self": {
              "href": "https://api.example.com/v1/comments/d0824ce5-2d7c-4893-b9c3-6f1da2de5c73",
              "type": "application/json" },
            "note": {
              "href": "https://api.example.com/v1/notes/85f33c5e-08e5-4283-a2a5-875fcd886215",
              "type": "application/json" },
            "creator": {
              "href": "https://api.example.com/v1/api_users/eb2471eb-8e67-40d5-ad06-992c5df58ef5",
              "type": "application/json" },
            "updater": {
              "href": "https://api.example.com/v1/api_users/925a4d7f-83c7-4485-bb74-ca6d3158c7ec",
              "type": "application/json" }
         },
          "body": "Are you really, really sure we need milk?",
          "created_at": "2013-08-02T18:12:53Z",
          "updated_at": "2013-08-05T09:59:17Z",
          "lock_version": 0
  }
}

Hyperlinks

The following hyperlink names are used in the following subsections. To retrieve the URL and Content-Type to use, use the _links hash. Note that the URI may change, and thus you should make no inference on how to construct similar URIs from any previous URI. For more information, refer to Hyperlink URIs are Opaque. You may store hyperlink URIs in permanent storage for later use.

The hyperlinks for a Comment resource are:

self
as always, the self hyperlink can be used to perform CRUD actions on the Note resource.
note
the Note to which this comment belongs.
creator
the ApiUser who created this Note.
updater
the ApiUser who last updated this Note.


GET self

Retrieves a Comment resource.

200
The operation was successful.
400
The X-API-Token header was missing or the token is unknown. Reauthenticate and retry the operation.
403
You don't have authorisation to read Comments.
404
The Comment resource wasn't found.
419
The X-API-Token has expired. Reauthenticate and retry the operation.

PUT self

Updates a Comment resource.

PUT requests, according to the RFC standard, require all resource attributes to be updated simultaneously. However, in Ocean PUT requests have the same semantics as PATCH requests in that it's possible to set individual attributes. The API will reject requests with missing essential attributes. If you receive unknown properties, you must preserve them and pass them back unchanged in PUT and PATCH requests. Other than that, you should ignore them. This enables the API to be upgraded transparently.

200
The operation was successful.
400
The X-API-Token header was missing or the token is unknown. Reauthenticate and retry the operation.
403
You don't have authorisation to modify Comments.
404
The Comment resource wasn't found.
409
The resource can't be saved, as it would overwrite a newer version of the same resource.
419
The X-API-Token has expired. Reauthenticate and retry the operation.
422
The data submitted wasn't valid. Examine the response body, which contains a standardised JSON error message object. The error message object enumerates in plain text the respective errors encountered for each attribute. If these errors are the result of user interaction, you should present them to the user. For more information, see Error Information.

DELETE self

Deletes a Comment resource.

204
The delete operation was successful.
400
The X-API-Token header was missing or the token is unknown. Reauthenticate and retry the operation.
403
You don't have authorisation to delete Comments.
404
The Comment resource wasn't found. DELETE requests are idempotent: thus, this is not really an error.
419
The X-API-Token has expired. Reauthenticate and retry the operation.

GET /v1/comments

Returns a collection of Comments. The basic URL returns all Comments in the system. You can add query arguments to the basic URL to perform matches and substring searches, and you can also group on a property.

You can match on the following property:

  • body

The following returns all Comments whose body property is media:

GET /v1/comments?body=media

You can also search on substrings in body by using search, for instance:

GET /v1/comments?search=Groups

Pagination can also be performed using page:

GET /v1/comments?page=3

The first page is 0. Page size defaults to 25, but can be changed using page_size:

GET /v1/comments?page=0&page_size=100
200
The operation was successful. The collection is returned as a JSON array in the response body.
400
The X-API-Token header was missing or the token is unknown. Reauthenticate and retry the operation.
403
You don't have authorisation to retrieve Comment collections.
419
The X-API-Token has expired. Reauthenticate and retry the operation.