Key idea
REST is a common way to lay out a web API: every kind of thing is a resource with its own path, and the HTTP method says what to do with it. Read the method and the path together and you know what an endpoint does before you call it.
Resources, paths and ids
A notes app has one resource, notes. Its API gives the collection a path, and each note a path under it with the note's id:
/notesis every note./notes/42is the note whose id is 42.
Reference docs write the id as a placeholder, /notes/{id}: read it as "any note's id goes here". Paths name things with nouns, usually plural. Nested paths show that one thing belongs to another: /projects/7/notes reads as "the notes in project 7".
Methods say what to do
The same path does different things with different methods:
| Request | Does | Typical success |
|---|---|---|
GET /notes | List the notes | 200 and a list |
GET /notes/42 | Fetch note 42 | 200 and one note |
POST /notes | Create a note from the body | 201 and the new note |
PUT /notes/42 | Replace note 42 with the body | 200 |
PATCH /notes/42 | Change some of note 42's fields | 200 |
DELETE /notes/42 | Remove note 42 | 204, no body |
For a POST, the server usually assigns the id and returns it in the response. A GET shouldn't change anything, so it's the safe one to try while you explore an API.
Query strings filter and page
A query string narrows a list without naming a new resource. GET /notes?done=false&limit=20 still means "the notes", just the first 20 that aren't done. Filters, sorting and paging usually live here.
Reading JSON
Most APIs send and receive JSON (JavaScript Object Notation), plain text any language can read:
{
"id": 42,
"text": "Renew the domain",
"done": false,
"tags": ["admin", "billing"],
"owner": { "id": 7, "name": "Ada" },
"due": null
}
Curly braces hold an object: names in double quotes, each with a value. Values are strings (in double quotes), numbers, true or false, null, a list in square brackets, or another object. The request and response say they're JSON with the header Content-Type: application/json.
Is every JSON API REST?
No. REST is a style, and many APIs follow it loosely, for example with a POST /notes/42/archive for an action that isn't a plain create or update. Others use a different style altogether, such as GraphQL, which sends every request to one path with a query in the body. What stays the same is the contract: the reference docs tell you the method, path, body and responses for each operation.
Check yourself