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

• (a) GET — reading, never changes state (it is safe).
• (b) DELETE — removes a known item at a known URI.
• (c) POST — creating on a collection when the server assigns the id.
• (d) PATCH — a partial update of one field; PUT would risk wiping the fields you didn't send.

Recall the class rule: $\text{2xx}=\text{success},\text{3xx}=\text{redirect},\text{4xx}=\text{client’s fault},\text{5xx}=\text{server’s fault}$

• 204 → 2xx success (success, nothing to return).
• 301 → 3xx redirect.
• 403 → 4xx client-fault (forbidden).
• 500 → 5xx server-fault.
• 429 → 4xx client-fault (too many requests — the client sent too many).
• 201 → 2xx success (created).

Keep the two definitions in mind: safe = no state change at all; idempotent = repeat-safe (same final state).

• GET — safe ✅, idempotent ✅ (reading twice = reading once, changes nothing).
• POST — safe ✗, idempotent ✗ (two creates = two rows).
• PUT — safe ✗ (it writes), idempotent ✅ (replace to the same value twice = same final state).
• DELETE — safe ✗, idempotent ✅ (deleting an already-deleted thing leaves it deleted).

More depth in Idempotency and retries.

• (a) 201 Created + a Location: /v1/users/42 header so the client learns the new URI.
• (b) 204 No Content — success with an empty body.
• (c) 401 Unauthorized — we don't know who you are (authentication missing).
• (d) 403 Forbidden — we know who you are, you're just not allowed (authorization). See Authentication vs Authorization.
• (e) 409 Conflict — the request clashes with current server state (duplicate email).

Use $\text{offset}(p)=(p-1)\cdot L$.

• (a) $\text{offset}(4)=(4-1)\times 25=75$.
• (b) Page $p$ covers indices $[(p-1)L,pL)=[75,100)$. Using the half-open convention defined at the top of the page, that square-then-round bracket means include 75, exclude 100 — i.e. rows 75 through 99, which is exactly $100-75=25$ rows.
• (c) Round up because leftovers still need a page: $\text{pages}=\lceil \frac{118}{25}\rceil =\lceil 4.72\rceil =5.$ Check: 4 full pages cover $4\times 25=100$ rows; 18 rows remain, needing a 5th page. ✅

PUT = full replace. Fields you omit are treated as "not present", so name and bio get wiped/defaulted: $\{\text{"email":"ada@new.com"}\}(\text{name and bio gone}).$ The client wanted to change one field, so it should have sent PATCH (partial merge), leaving name and bio intact.

What happens. With newest-first ordering, inserting 3 posts at the top pushes every existing post down by 3 index positions. Page 1 already showed the old top-10 (old indices 0–9). Now:

• The 3 new posts occupy new indices 0–2.
• Old posts 0–6 now sit at new indices 3–9 — but the client already saw them on page 1.
• Page 2 requests offset=10, limit=10 → new indices 10–19. Old index 7,8,9 have moved to new indices 10,11,12 — so the user sees old posts #7, #8, #9 again (duplicates, the yellow dashed boxes in Figure 2), and the truly-next items get pushed off.

In general, inserting $k$ items at the top makes the last $k$ items of the previous page reappear at the start of the next page (or, for deletions, makes $k$ items get skipped).

The fix: cursor (keyset) pagination. Instead of "skip 10", remember the sort key of the last item you showed and ask for items strictly past it: $\text{WHERE id < :last\_id ORDER BY id DESC LIMIT 10}$ Now new posts at the top don't affect the window at all — the cursor points at a fixed row, not a shifting count.

• (a) Offset/limit — you need to jump to arbitrary page 137, which offset supports directly and cursor cannot.
• (b) Cursor — the data is live and huge; cursor is stable under inserts and fast at any depth (a WHERE id < cursor uses the index — see Database indexing — instead of scanning millions of skipped rows).
• (c) Offset/limit — "last page" means offset = (pages-1)*L, a random jump only offset gives you. (Cursor can't leap to the end.)

WHY each status, row by row:

• List → 200 OK: a GET that returns data uses the generic success code with the collection in the body. (An empty list is still a 200 with [], not a 404 — the collection exists, it's just empty.)
• Read one → 200 OK: same reasoning; the single comment is returned in the body. Only if comment 88 doesn't exist would this become 404.
• Create → 201 Created + Location: POST made a new resource, so we use the more specific Created code (not plain 200) and add a Location: /v1/posts/5/comments/88 header so the client learns the URI of the thing it just made.
• Edit text → 200 OK: the PATCH succeeded and we return the updated comment, so generic success with a body. (Some APIs use 204 if they return nothing, but returning the fresh state is friendlier.)
• Delete → 204 No Content: the delete worked and there's nothing meaningful to send back, so No Content — success with an empty body, which is the conventional DELETE reply.

Idempotent ones: the GETs, the PATCH here (writing the same text twice ends identically), and DELETE. The POST is not idempotent — resending creates a second comment. Note the URLs name nouns (comments), never actions.

• (a) Additive/safe — old clients ignore the new field. No /v2 needed.
• (b) Breaking — renaming a field breaks every client reading email. Needs /v2 (or dual-write both keys for a deprecation window).
• (c) Breaking — old clients that omit country now get rejected. Needs /v2.
• (d) Additive/safe — a new endpoint touches no existing client.

Design goal: keep changes additive so you bump the major version rarely. More in API versioning and backward compatibility.

• (a) POST is not idempotent. The retry creates a second payment 901 → the customer is charged $100 for one $50 purchase.
• (b) Attach an idempotency key: the client generates a unique key once and sends it on the first attempt and every retry (e.g. header Idempotency-Key: abc-123). The server records "key abc-123 → payment 900". On the retry it sees the key already exists and returns the stored result instead of charging again. (This is precisely how real payment APIs turn a non-idempotent POST into a safely-retryable one — see Idempotency and retries.)
• (c) Recommended: replay the original 201 Created with payment 900's stored body. The reasoning: the retry must look to the client exactly like the request that (unknown to it) already succeeded — and that original request created a resource, whose correct code is 201. So the server replays the stored 201 and the same Location: /v1/payments/900. A plain 200 OK is an acceptable fallback if you don't cache the full original response, but you must never return a fresh 201 for a new charge, and never 409 (nothing conflicts — it's the same logical request). The client must observe exactly one successful $50 charge.

• (a) $\text{pages}=\lceil \frac{1000}{30}\rceil =\lceil 33.33\dots \rceil =34$.
• (b) The last page is page 34, so $\text{offset}(34)=(34-1)\times 30=990$.
• (c) The last page covers indices $[990,1000)$. Using our half-open convention this includes 990, excludes 1000, so it returns $1000-990=10$ rows. Note we clamp the top at $N=1000$, not at $34\times 30=1020$ — the naive "every page has 30 rows" assumption would over-count here.
• (d) Because the table is a fast-growing live log, /v2 should ship cursor (keyset) pagination: it stays stable under the constant inserts (no duplicate/skipped events, unlike offset — recall Exercise 3.1) and is fast at any depth (an indexed WHERE id < :cursor instead of scanning 990+ skipped rows). Offset would have been the wrong call here despite looking simpler.

GET is both safe and idempotent. A create-on-collection uses the method POST and returns 201 Created with a Location header. Authenticated-but-forbidden is status 403; unauthenticated is 401. offset(p) = ==$(p-1)\cdot L$== and total pages = ==$\lceil N/L\rceil$. Pagination that is stable under inserts and fast at any depth is cursor (keyset)== pagination.