--- 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) %>