206 lines
7.2 KiB
Plaintext
206 lines
7.2 KiB
Plaintext
---
|
|
title: REST Notes API Guide
|
|
|
|
language_tabs:
|
|
- shell
|
|
- http
|
|
|
|
search: true
|
|
---
|
|
|
|
# Overview
|
|
|
|
|
|
## 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
|
|
|
|
## 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
|
|
|
|
## Errors
|
|
|
|
<%= ERB.new(File.read("../build/generated-snippets/error-example/http-response.md")).result(binding) %>
|
|
|
|
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:
|
|
|
|
<%= ERB.new(File.read("../build/generated-snippets/error-example/response-fields.md")).result(binding) %>
|
|
|
|
## Hypermedia
|
|
|
|
RESTful Notes uses hypermedia and resources include links to other resources in their
|
|
responses. Responses are in [Hypertext Application Language (HAL)](https://github.com/mikekelly/hal_specification)
|
|
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
|
|
|
|
|
|
|
|
## Index
|
|
|
|
<%= ERB.new(File.read("../build/generated-snippets/index-example/curl-request.md")).result(binding) %>
|
|
<%= ERB.new(File.read("../build/generated-snippets/index-example/http-request.md")).result(binding) %>
|
|
<%= ERB.new(File.read("../build/generated-snippets/index-example/http-response.md")).result(binding) %>
|
|
|
|
The index provides the entry point into the service. A `GET` request is used to access the index.
|
|
|
|
### Response structure
|
|
|
|
<%= ERB.new(File.read("../build/generated-snippets/index-example/response-fields.md")).result(binding) %>
|
|
|
|
### Links
|
|
|
|
<%= ERB.new(File.read("../build/generated-snippets/index-example/links.md")).result(binding) %>
|
|
|
|
|
|
|
|
## Notes
|
|
|
|
The Notes resources is used to create and list notes
|
|
|
|
### Listing notes
|
|
|
|
<%= ERB.new(File.read("../build/generated-snippets/notes-list-example/http-request.md")).result(binding) %>
|
|
<%= ERB.new(File.read("../build/generated-snippets/notes-list-example/http-response.md")).result(binding) %>
|
|
<%= ERB.new(File.read("../build/generated-snippets/notes-list-example/curl-request.md")).result(binding) %>
|
|
|
|
A `GET` request will list all of the service's notes.
|
|
|
|
#### Response structure
|
|
|
|
<%= ERB.new(File.read("../build/generated-snippets/notes-list-example/response-fields.md")).result(binding) %>
|
|
|
|
### Creating a note
|
|
|
|
<%= ERB.new(File.read("../build/generated-snippets/notes-create-example/http-request.md")).result(binding) %>
|
|
<%= ERB.new(File.read("../build/generated-snippets/notes-create-example/http-response.md")).result(binding) %>
|
|
<%= ERB.new(File.read("../build/generated-snippets/notes-create-example/curl-request.md")).result(binding) %>
|
|
|
|
A `POST` request is used to create a note
|
|
|
|
#### Request structure
|
|
|
|
<%= ERB.new(File.read("../build/generated-snippets/notes-create-example/request-fields.md")).result(binding) %>
|
|
|
|
|
|
|
|
## Tags
|
|
|
|
The Tags resource is used to create and list tags.
|
|
|
|
### Listing tags
|
|
|
|
<%= ERB.new(File.read("../build/generated-snippets/tags-list-example/curl-request.md")).result(binding) %>
|
|
<%= ERB.new(File.read("../build/generated-snippets/tags-list-example/http-request.md")).result(binding) %>
|
|
<%= ERB.new(File.read("../build/generated-snippets/tags-list-example/http-response.md")).result(binding) %>
|
|
|
|
A `GET` request will list all of the service's tags.
|
|
|
|
#### Response structure
|
|
|
|
<%= ERB.new(File.read("../build/generated-snippets/tags-list-example/response-fields.md")).result(binding) %>
|
|
|
|
|
|
### Creating a tag
|
|
|
|
<%= ERB.new(File.read("../build/generated-snippets/tags-create-example/curl-request.md")).result(binding) %>
|
|
<%= ERB.new(File.read("../build/generated-snippets/tags-create-example/http-request.md")).result(binding) %>
|
|
<%= ERB.new(File.read("../build/generated-snippets/notes-create-example/http-response.md")).result(binding) %>
|
|
|
|
A `POST` request is used to create a tag
|
|
|
|
#### Request structure
|
|
|
|
<%= ERB.new(File.read("../build/generated-snippets/tags-create-example/request-fields.md")).result(binding) %>
|
|
|
|
|
|
|
|
## Note
|
|
|
|
The Note resource is used to retrieve, update, and delete individual notes
|
|
|
|
### Retrieve a note
|
|
|
|
<%= ERB.new(File.read("../build/generated-snippets/note-get-example/http-request.md")).result(binding) %>
|
|
<%= ERB.new(File.read("../build/generated-snippets/note-get-example/curl-request.md")).result(binding) %>
|
|
<%= ERB.new(File.read("../build/generated-snippets/note-get-example/http-response.md")).result(binding) %>
|
|
|
|
A `GET` request will retrieve the details of a note
|
|
|
|
<%= ERB.new(File.read("../build/generated-snippets/note-get-example/response-fields.md")).result(binding) %>
|
|
|
|
#### Links
|
|
|
|
<%= ERB.new(File.read("../build/generated-snippets/note-get-example/links.md")).result(binding) %>
|
|
|
|
### Update a note
|
|
|
|
<%= ERB.new(File.read("../build/generated-snippets/note-update-example/curl-request.md")).result(binding) %>
|
|
<%= ERB.new(File.read("../build/generated-snippets/note-update-example/http-request.md")).result(binding) %>
|
|
<%= ERB.new(File.read("../build/generated-snippets/note-update-example/http-response.md")).result(binding) %>
|
|
|
|
A `PATCH` request is used to update a note
|
|
|
|
#### Request structure
|
|
|
|
<%= ERB.new(File.read("../build/generated-snippets/note-update-example/request-fields.md")).result(binding) %>
|
|
|
|
To leave an attribute of a note unchanged, any of the above may be omitted from the
|
|
request.
|
|
|
|
|
|
|
|
## Tag
|
|
|
|
The Tag resource is used to retrieve, update, and delete individual tags
|
|
|
|
### Retrieve a tag
|
|
|
|
<%= ERB.new(File.read("../build/generated-snippets/tag-get-example/curl-request.md")).result(binding) %>
|
|
<%= ERB.new(File.read("../build/generated-snippets/tag-get-example/http-request.md")).result(binding) %>
|
|
<%= ERB.new(File.read("../build/generated-snippets/tag-get-example/http-response.md")).result(binding) %>
|
|
|
|
A `GET` request will retrieve the details of a tag
|
|
|
|
#### Response structure
|
|
|
|
<%= ERB.new(File.read("../build/generated-snippets/tag-get-example/response-fields.md")).result(binding) %>
|
|
|
|
#### Links
|
|
|
|
<%= ERB.new(File.read("../build/generated-snippets/tag-get-example/links.md")).result(binding) %>
|
|
|
|
### Update a tag
|
|
|
|
<%= ERB.new(File.read("../build/generated-snippets/tag-update-example/curl-request.md")).result(binding) %>
|
|
<%= ERB.new(File.read("../build/generated-snippets/tag-update-example/http-request.md")).result(binding) %>
|
|
<%= ERB.new(File.read("../build/generated-snippets/tag-update-example/http-response.md")).result(binding) %>
|
|
|
|
A `PATCH` request is used to update a tag
|
|
|
|
#### Request structure
|
|
|
|
<%= ERB.new(File.read("../build/generated-snippets/tag-update-example/request-fields.md")).result(binding) %> |