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