Creating a Note

To add a note titled “Groceries”, the client sends a POST request:

POST /notes HTTP/1.1
Host: api.notes.example
Content-Type: application/json

{
  "title": "Groceries",
  "body": "Milk, eggs, bread"
}

Note that the request is to the collection, /notes, not to a specific note. This might seem counterintuitive, since the client is creating one note, not the whole collection. By convention, you create a new resource by sending the request to the endpoint of the collection it belongs to.

The request header may include authentication credentials, but we are leaving that out of scope. In a real system, the server needs to know which user is creating the note, so it can store the note with that user.

The server creates the note and sends this response:

HTTP/1.1 201 Created
Location: /notes/42
Content-Type: application/json

{
  "id": 42,
  "title": "Groceries",
  "body": "Milk, eggs, bread",
  "created_at": "2026-09-20T09:15:00Z",
  "updated_at": "2026-09-20T09:15:00Z"
}

The status is 201 Created. It signals that the request succeeded (similar to a 200 OK), and a new resource was created as a result.

The Location header holds the path of the new note. The client uses it later to read, replace, or delete the note. The body is the representation of the new note, including the identifier and the timestamps the server set, so the client has them without sending another request.

A request the server refuses

Suppose a client sends a body without a title:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "A note needs a title."
}

The server checks the request before it creates anything. A request that gets a 400 creates no note. The same happens when the title is empty or too long, and when the body includes a field that only the server may set. The error body has the same shape as before: an error field with a message that a developer can read.