HTTP Methods & Status Codes for Resource APIs
Interviewers expect CRUD mapped to methods and status codes clients can automate on. Always-200 with {success:false} is a classic fail. This lesson covers GET/POST/PUT/PATCH/DELETE, 201 Location, Prefer, If-Match, and the 4xx grid — pointing POST retries and 429 at the Idempotency and rate-limit docs.
- 1Gist
- 2Maps
- 3Q&A
- 4Sandbox
Voice readout needs Web Speech Synthesis in this browser.
How clients automate on your responses
Prefer
Real status codes plus problem+json
2xx means success. 4xx means the client can branch. RFC 9457 gives a consistent error shape. Prefer and If-Match are how you avoid huge bodies and lost updates.
- 201 Location is the canonical item URL — no guessing ids.
- 412 on If-Match beats last-write-wins.
- 409 is state conflict (already voided), not schema validation.
Alternative
Always 200 with {success:false}
Easy for a naive SPA. Breaks caches, CDNs, HTTP tooling, and interview expectations. PUT used as PATCH. Create without Location.
- Caches store failures as success.
- Gateways cannot retry or shed load on status.
- 409 for validation confuses conflict with bad JSON.
Method to status
Validate first. Store second. Headers decide body size and concurrency.
- 1
Parse method + path
Collection vs item. Unknown method → 405. - 2
If-Match / Prefer
Stale ETag → 412. Prefer return=minimal shrinks create/update bodies. - 3
Authz + validate
401 missing creds, 403 forbidden, 404 hide-or-not, 422 semantic. - 4
Mutate or read
201 Location on create. 202 job URL if async. 204 on delete if you pick empty.
Overview
Interviewers expect you to map CRUD to methods correctly and pick status codes clients can automate on. Always-200 with {success:false} is a classic fail.
For POST retries and 429 handling, cross-link the Idempotency and rate-limit docs — do not re-teach Idempotency-Key, RFC safe-vs-idempotent deep dives, or outbox patterns here.
Methods on collections vs items
GET /orders— list (filter/page in query);GET /orders/{id}— read one.POST /orders— create; body = new resource; response often 201 + Location.PUT /orders/{id}— replace entire representation (client sends full resource); idempotent replace.PATCH /orders/{id}— partial update; define merge semantics (JSON Merge Patch / JSON Patch).DELETE /orders/{id}— remove; 204 empty or 200 with body — pick one.- Avoid
PUT /ordersfor create-without-id unless you control client-generated ids.
Status codes worth memorizing
| Code | Meaning | Interview use |
|---|---|---|
| 200 | Success with body | Read, replace, or delete-with-body |
| 201 | Created | Prefer Location to the canonical item |
| 202 | Accepted | Async; resource may not exist yet — return a job URL |
| 204 | No content | Success, empty body (common for DELETE) |
| 400 | Bad request | Syntax / validation shape |
| 401 | Unauthenticated | Missing or invalid credentials |
| 403 | Forbidden | Identity known, not allowed |
| 404 | Not found | Or hide existence — document the policy |
| 409 | Conflict | Duplicate, already voided — state |
| 412 | Precondition failed | If-Match lost the race |
| 422 | Unprocessable | Semantic validation when you distinguish from 400 |
| 429 | Too many requests | 429 / Retry-After |
| 500 / 503 | Server / overload | 503 for planned unavailability |
Prefer and conditional headers
Prefer: return=representationvsreturn=minimal— control create/update response body size.If-Match/ETag— optimistic concurrency; fail with 412 rather than silent clobber.If-None-Matchon GET — 304 for caches.
When 201 Location matters: clients and gateways fetch the created resource without guessing IDs. Return an absolute or rooted path to the canonical item URL. Pair with a body when Prefer asks for representation.
Flow
- 1
1 Method + path
- next2 Validate + authz
- 2
2 Validate + authz
- ok3 Store
- conflict / 4124 4xx problem+json
- 3
3 Store
- next5 2xx Location ETag
- 4
4 4xx problem+json
- 5
5 2xx Location ETag
Lesson map
HTTP Methods & Status Codes for Resource APIs
Interviewers expect CRUD mapped to methods and status codes clients can automate on. Always-200 with {success:false} is a classic fail. This lesson covers GET/POST/PUT/PATCH/DELETE, 201 Location, Prefer, If-Match, and the 4xx grid — pointing POST retries and 429 at the Idempotency and rate-limit docs.
Architecture. Architecture
Select a node to see why it exists, or an edge to see the protocol, direction, effect, and consequence.
Mermaid export
flowchart TB m["1 Method + path"] v["2 Validate + authz"] s["3 Store"] e["4 4xx problem+json"] m -->|1 Method + path to 2 Validate + authz| v v -->|ok| s v -->|conflict / 412| e
Sandbox: method to status (Python)
Didactic mapping — not a full HTTP server. Stale If-Match returns 412. PATCH on a missing item returns 404.
Press Run. Snippets must be self-contained — no network, files, or native modules.
Same mapping (TypeScript)
Press Run. Snippets must be self-contained — no network, files, or native modules.
Deep dive · 404 vs 403 existence leak
If /orders/{id} 403s for another tenant's id, you confirmed the order exists. Many products return 404 to hide existence. That is a policy, not a universal rule — document it. Do not mix 404-hide on some resources and 403 on others without a story.
Pitfalls
First POST /invoices/inv_3:void → 200. Second → 409 already void, not 200 and not 422. Where does Location go on the original create? What ETag does the second call If-Match?
Interview Q&A
PUT vs PATCH?
Answer
PUT replaces the entire representation. PATCH is partial — name JSON Merge Patch or JSON Patch. PUT without If-Match risks lost updates.
Why 201 Location?
Answer
Tells clients the canonical URL of the new resource. Important for follow-up GET, redirects, and gateways. Pair with a body when Prefer asks for representation.
401 vs 403?
Answer
401 = missing or invalid credentials. 403 = identity known but not allowed. Do not 401 a logged-in user who failed RBAC.
Is POST idempotent?
Answer
Not by default. Design keys and fingerprints; see api-idempotency-keys. Do not re-teach the key state machine on this page. PUT replace is idempotent by HTTP semantics — method truth.
202 vs 201?
Answer
202 means accepted for async processing; the resource may not exist yet — return a job URL. 201 means the resource exists now at Location.
When 204 vs 200 on DELETE?
Answer
204 if you return no body. 200 if you return the deleted representation. Pick one API-wide. Do not 200 with an empty body just to look friendly.
412 vs 409?
Answer
412 is a failed precondition (If-Match). 409 is a business state conflict (duplicate create, already voided). Both are client-visible; they are not interchangeable.
Prefer header?
Answer
return=representation vs return=minimal (RFC 7240). Saves payload on chatty mobile clients after create/update.
Always-200?
Answer
Breaks caches, HTTP tooling, and CDNs. Prefer status + RFC 9457 problem details.
What about 429?
Answer
Quota deny with Retry-After. Depth: 429 headers and backoff. This page only names the code.