APIs
Status codes: ship an honest API
Reading about status codes is not the same as shipping an API that gets them right when an upstream dies, a client floods you, and two writers race the same record. Build a small service whose status line tells the truth under all three, and prove it with a test suite that asserts on the wire — not on your intentions.
Turn the unit’s model into a working contract: emit the correct class and sub-code for every outcome, attach the right headers (Location, Retry-After, ETag), keep error detail in the body of an honest status, make retries safe with idempotency, and verify every rule with a black-box conformance test.
Build a small order/payment HTTP API (any language) whose status codes are correct across creation, async work, the full 4xx vocabulary, fault-attributed 5xx, rate limiting, and idempotent retries — then write a black-box conformance test that drives it through each scenario and asserts on the actual status line, headers, and body.
- Every endpoint returns the correct class and sub-code for each outcome, verified by the conformance test asserting on the status line (not on the body's ok flag) — 201+Location, 202+poll URL, 204, 400/422/409/401/403, 500/502/504, 429/503.
- 429 and 503 responses always carry a Retry-After header; the test asserts it is present and parseable.
- Replaying a request with the same Idempotency-Key produces exactly one order/charge and returns the original response; the test proves no duplicate is created.
- A conditional PUT with a stale If-Match returns 412 and does not overwrite; with a fresh If-Match it succeeds — both asserted by the test.
- No error path returns 200; a test that asserts 'status is 2xx implies success' passes, i.e. there is no success-shaped failure anywhere.
- Add a thin client SDK with a correct retry policy: retry 5xx and 429 only, honour Retry-After before exponential backoff with jitter, never retry a non-idempotent request without an Idempotency-Key, and reconcile on an ambiguous 504.
- Add observability: emit a metric labelled by status class and assert in the test that an injected upstream outage moves the 5xx counter (proving the dashboard would have caught the gateway-incident scenario).
- Add a 404-instead-of-403 mode for sensitive resources and document the security trade-off (hiding existence vs REST correctness) you are making.
- Run the conformance suite in CI as a gate, and add a contract snapshot so a future change that downgrades a 422 back to a generic 400 fails the build.
This is the loop behind a service whose status codes you can trust in an incident: design the contract so the class and sub-code tell the truth, attach the headers that make clients behave (Location, Retry-After, ETag), keep detail in the body of an honest status, make writes idempotent so retries cannot double-charge, and prove every rule with a black-box test that asserts on the wire rather than on your intentions. Doing it once on a toy API is what makes the production version reflexive.