Foundations — REST API design — resources, HTTP methods, status codes, versioning, pagination

Before you can read the parent note, you need to own every piece of notation it quietly assumes. We build each one from nothing, anchor it to a picture, and say why the topic needs it. Read top to bottom — each brick sits on the previous one.

1. Client and Server — who is talking to whom

Picture two people passing notes. One person (the client) writes a request note and hands it over; the other (the server) reads it, does the work, and hands back a reply note. Neither ever sees inside the other's brain — only the notes cross the gap.

Related deeper reading: HTTP protocol.

2. HTTP — the language the notes are written in

Every request note in HTTP has the same fixed layout:

And every reply note:

You'll meet each labelled part below. Notice the parent note's whole structure — "HTTP Methods", "Status Codes", "the body is JSON" — is just: fill in these blanks.

3. URL / URI — the street address

Break the address into parts you can see:

• /users — a collection (a folder holding many things).
• /users/42 — one item inside it (the user whose id is 42).
• ?limit=20&offset=40 — the query string: extra knobs after the ?, joined by &, each written key=value.

The / slash separates levels, like folders on a computer. Reading /users/42/orders/7 left to right: "inside users, the one with id 42, inside its orders, the one with id 7."

4. Resource, state, and representation (JSON)

$\text{{ "name": "Ada", "email": "ada@x.com" }}$

Read it as a labelled box: the key "name" points at the value "Ada". Square brackets [ ... ] mean a list, e.g. [ {...}, {...} ] is "a list of two boxes".

5. The METHOD — the verb slot

Picture the same address /users/42 as a mailbox, and the method as a rubber stamp you press on the envelope before sending:

• GET stamp = "send me a copy" (read).
• POST stamp = "here's a new one, file it" (create).
• PUT stamp = "replace what's there with this".
• PATCH stamp = "change just these fields".
• DELETE stamp = "throw it away".

Two words the parent leans on hard:

Deeper: Idempotency and retries.

6. Headers — the side-notes

Picture sticky notes on the outside of the envelope — the letter inside is the body; the sticky notes are headers telling the sorter how to handle it.

7. Status code — the reply's headline

The first digit is a family. Think of it as the mood of the reply:

8. Two number tools for pagination: ⌈ ⌉ and ⌊ ⌋

The pagination section uses two symbols a 12-year-old may not have met.

Interval notation the parent uses: $[a,b)$ means "from $a$ included up to $b$ excluded". Page $p$ covers rows $[(p-1)L,pL)$ — the square bracket grabs the start row, the round bracket stops just before the next page's first row, so no row is counted twice.

How these foundations feed the topic

Read the arrows as "you need this before that." Everything funnels into REST API design — the parent note (topic).

Equipment checklist

Cover the answers. If you can say each one aloud, you're ready for the parent note.