229 lines
4.6 KiB
Plaintext
229 lines
4.6 KiB
Plaintext
= RESTful Notes API Guide
|
|
Andy Wilkinson;
|
|
:doctype: book
|
|
:icons: font
|
|
:source-highlighter: highlightjs
|
|
:toc: left
|
|
:toclevels: 4
|
|
:sectlinks:
|
|
:operation-curl-request-title: Example request
|
|
:operation-http-response-title: Example response
|
|
|
|
[[overview]]
|
|
= Overview
|
|
|
|
[[overview-http-verbs]]
|
|
== HTTP verbs
|
|
|
|
RESTful notes tries to adhere as closely as possible to standard HTTP and REST conventions in its
|
|
use of HTTP verbs.
|
|
|
|
|===
|
|
| Verb | Usage
|
|
|
|
| `GET`
|
|
| Used to retrieve a resource
|
|
|
|
| `POST`
|
|
| Used to create a new resource
|
|
|
|
| `PATCH`
|
|
| Used to update an existing resource, including partial updates
|
|
|
|
| `DELETE`
|
|
| Used to delete an existing resource
|
|
|===
|
|
|
|
[[overview-http-status-codes]]
|
|
== HTTP status codes
|
|
|
|
RESTful notes tries to adhere as closely as possible to standard HTTP and REST conventions in its
|
|
use of HTTP status codes.
|
|
|
|
|===
|
|
| Status code | Usage
|
|
|
|
| `200 OK`
|
|
| The request completed successfully
|
|
|
|
| `201 Created`
|
|
| A new resource has been created successfully. The resource's URI is available from the response's
|
|
`Location` header
|
|
|
|
| `204 No Content`
|
|
| An update to an existing resource has been applied successfully
|
|
|
|
| `400 Bad Request`
|
|
| The request was malformed. The response body will include an error providing further information
|
|
|
|
| `404 Not Found`
|
|
| The requested resource did not exist
|
|
|===
|
|
|
|
[[overview-errors]]
|
|
== Errors
|
|
|
|
Whenever an error response (status code >= 400) is returned, the body will contain a JSON object
|
|
that describes the problem. The error object has the following structure:
|
|
|
|
include::{snippets}/error-example/response-fields.adoc[]
|
|
|
|
For example, a request that attempts to apply a non-existent tag to a note will produce a
|
|
`400 Bad Request` response:
|
|
|
|
include::{snippets}/error-example/http-response.adoc[]
|
|
|
|
[[overview-hypermedia]]
|
|
== Hypermedia
|
|
|
|
RESTful Notes uses hypermedia and resources include links to other resources in their
|
|
responses. Responses are in http://stateless.co/hal_specification.html[Hypertext Application
|
|
from resource to resource.
|
|
Language (HAL)] format. Links can be found beneath the `_links` key. Users of the API should
|
|
not create URIs themselves, instead they should use the above-described links to navigate
|
|
|
|
[[resources]]
|
|
= Resources
|
|
|
|
|
|
|
|
[[resources-index]]
|
|
== Index
|
|
|
|
The index provides the entry point into the service.
|
|
|
|
|
|
|
|
[[resources-index-access]]
|
|
=== Accessing the index
|
|
|
|
A `GET` request is used to access the index
|
|
|
|
operation::index-example[snippets='response-fields,http-response,links']
|
|
|
|
|
|
|
|
[[resources-notes]]
|
|
== Notes
|
|
|
|
The Notes resources is used to create and list notes
|
|
|
|
|
|
|
|
[[resources-notes-list]]
|
|
=== Listing notes
|
|
|
|
A `GET` request will list all of the service's notes.
|
|
|
|
operation::notes-list-example[snippets='response-fields,curl-request,http-response,links']
|
|
|
|
|
|
|
|
[[resources-notes-create]]
|
|
=== Creating a note
|
|
|
|
A `POST` request is used to create a note.
|
|
|
|
operation::notes-create-example[snippets='request-fields,curl-request,http-response']
|
|
|
|
|
|
|
|
[[resources-tags]]
|
|
== Tags
|
|
|
|
The Tags resource is used to create and list tags.
|
|
|
|
|
|
|
|
[[resources-tags-list]]
|
|
=== Listing tags
|
|
|
|
A `GET` request will list all of the service's tags.
|
|
|
|
operation::tags-list-example[snippets='response-fields,curl-request,http-response,links']
|
|
|
|
|
|
|
|
[[resources-tags-create]]
|
|
=== Creating a tag
|
|
|
|
A `POST` request is used to create a note
|
|
|
|
operation::tags-create-example[snippets='request-fields,curl-request,http-response']
|
|
|
|
|
|
|
|
[[resources-note]]
|
|
== Note
|
|
|
|
The Note resource is used to retrieve, update, and delete individual notes
|
|
|
|
|
|
|
|
[[resources-note-links]]
|
|
=== Links
|
|
|
|
include::{snippets}/note-get-example/links.adoc[]
|
|
|
|
|
|
|
|
[[resources-note-retrieve]]
|
|
=== Retrieve a note
|
|
|
|
A `GET` request will retrieve the details of a note
|
|
|
|
operation::note-get-example[snippets='response-fields,curl-request-http-response']
|
|
|
|
|
|
|
|
[[resources-note-update]]
|
|
=== Update a note
|
|
|
|
A `PATCH` request is used to update a note
|
|
|
|
==== Request structure
|
|
|
|
include::{snippets}/note-update-example/request-fields.adoc[]
|
|
|
|
To leave an attribute of a note unchanged, any of the above may be omitted from the request.
|
|
|
|
==== Example request
|
|
|
|
include::{snippets}/note-update-example/curl-request.adoc[]
|
|
|
|
==== Example response
|
|
|
|
include::{snippets}/note-update-example/http-response.adoc[]
|
|
|
|
|
|
|
|
[[resources-tag]]
|
|
== Tag
|
|
|
|
The Tag resource is used to retrieve, update, and delete individual tags
|
|
|
|
|
|
|
|
[[resources-tag-links]]
|
|
=== Links
|
|
|
|
include::{snippets}/tag-get-example/links.adoc[]
|
|
|
|
|
|
|
|
[[resources-tag-retrieve]]
|
|
=== Retrieve a tag
|
|
|
|
A `GET` request will retrieve the details of a tag
|
|
|
|
operation::tag-get-example[snippets='response-fields,curl-request,http-response']
|
|
|
|
|
|
|
|
[[resources-tag-update]]
|
|
=== Update a tag
|
|
|
|
A `PATCH` request is used to update a tag
|
|
|
|
operation::tag-update-example[snippets='request-fields,curl-request,http-response']
|