The Note Resource

From Ocean Framework Documentation Wiki
Jump to: navigation, search

The Note 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/notes

Structure

title
(String) The title of the Note. Required.
body
(String) The body of the Note. Optional.
created_at
(String) A datetime string in GMT.
updated_at
(String) A datetime string in GMT.
{
 "note": {
          "_links": {
            "self": {
              "href": "https://api.example.com/v1/notes/8f1c860c-fd08-4f73-96b3-36e881f0518d",
              "type": "application/json" },
            "comments": {
              "href": "https://api.example.com/v1/notes/8f1c860c-fd08-4f73-96b3-36e881f0518d/comments",
              "type": "application/json" },
            "creator": {
              "href": "https://api.example.com/v1/api_users/2235bc79-1fb3-4da2-b1e3-add7f3c67906",
              "type": "application/json" },
            "updater": {
              "href": "https://api.example.com/v1/api_users/5f1f7e38-6b8a-4c01-81e7-f8b608c53d2c",
              "type": "application/json" }
         },
          "title": "My fantastic TODO note",
          "body": "Don't forget to buy milk. We're out.",
          "created_at": "2013-08-01T18:40:53Z",
          "updated_at": "2013-08-03T09:12:17Z",
          "lock_version": 2
  }
}

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 Note resource are:

self
as always, the self hyperlink can be used to perform CRUD actions on the Note resource.
comments
GET retrieves the collection of Comments belonging to this Note.
POST creates a new Comment belonging to this Note.
creator
the ApiUser who created this Note.
updater
the ApiUser who last updated this Note.


GET self

Retrieves a Note 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 Notes.
404
The Note resource wasn't found.
419
The X-API-Token has expired. Reauthenticate and retry the operation.

PUT self

Updates a Note 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 Notes.
404
The Note 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 Note 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 Notes.
404
The Note 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 comments

Returns the Comments belonging to this Post.

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 for Notes.
419
The X-API-Token has expired. Reauthenticate and retry the operation.

POST comments

Creates a new Comment for the Note. The body attribute is required.

201
The operation was successful and a new Comment resource has been created. The response headers will, as is customary, include a standard Location header giving the URI of the newly created resource. To save you the extra request Ocean also returns the new Comment resource 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 create Comments for Notes.
419
The X-API-Token has expired. Reauthenticate and retry the operation.
422
The POST data submitted wasn't valid. The response body contains a standardised JSON error message object. If the key _api_error is present, you have duplicate data: the error message object will tell you "Resource not unique". If the key _api_error isn't present, 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.


GET /v1/notes

Returns a collection of Notes. The basic URL returns all Notes 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:

  • title

The following returns all Notes whose title property is media:

GET /v1/notes?title=media

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

GET /v1/notes?body=Groups

Pagination can also be performed using page:

GET /v1/notes?page=3

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

GET /v1/notes?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 Note collections.
419
The X-API-Token has expired. Reauthenticate and retry the operation.

POST /v1/notes

Creates a new Note resource.

201
The operation was successful and a new Note resource has been created. The response headers will, as is customary, include a standard Location header giving the URI of the newly created resource. To save you the extra request Ocean also returns the new Note resource 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 create Notes.
419
The X-API-Token has expired. Reauthenticate and retry the operation.
422
The POST data submitted wasn't valid. The response body contains a standardised JSON error message object. If the key _api_error is present, you have duplicate data: the error message object will tell you "Resource not unique". If the key _api_error isn't present, 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.