Resources and Endpoints

The requirements say what the API must do. To design it, we decide which resources the API exposes, what endpoint each resource has, and which HTTP method each requirement uses.

The resource

Every requirement is about notes. A client creates a note, lists notes, reads one, replaces one, changes one, and deletes one. So the API has one resource, the note.

A note has a title and a body. The server also gives each note an identifier and two timestamps. Here is the representation of one note:

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

The client sets the title and the body. The server sets the id, created_at, and updated_at. The server changes updated_at whenever the title or the body changes. A request that includes a field the server sets gets 400 Bad Request. Otherwise a client could give a note an identifier it made up, or a creation time that is wrong.

The title is required and cannot be empty. It can have at most 100 characters. The body can be empty, and it can have at most 10,000 characters.

In the database, each note also belongs to one user. The database stores that information with the note, but we do not include it in the API response. So it is not part of the representation.

Endpoints

The endpoint for the collection of notes is /notes. The endpoint for one note is /notes/42, where 42 is the note’s identifier.

Methods

The familiar term CRUD groups operations into create, read, update, and delete. Each of them maps to an HTTP method:

• POST sends data to the server to create a resource.
• GET reads a resource.
• PUT replaces a resource with the version the client sends.
• PATCH changes part of a resource.
• DELETE removes a resource.

In CRUD terms, both PUT and PATCH are updates.

The requirements give us six requests:

The two GET requests work the way they did for the resources in the registrar API. We will focus on the other four requests, which change data on the server.