API design contracts — REST done deliberately

An API contract is the promise between producer and consumer. The design surface:

• Resource modeling: nouns not verbs (/access-requests, not /createAccessRequest); the hierarchy encodes ownership (/groups/{id}/members).
• Status codes as protocol: 201 (created), 200 (ok/duplicate), 202 (accepted, async), 401 (unauthenticated), 403 (authenticated, forbidden), 404 (missing), 409 (conflict — your conditional-update races!), 422/400 (validation), 503 (dependency down).
• Consistent envelopes: one error shape, everywhere.
• Pagination: offset (simple, breaks under inserts) vs keyset/cursor (stable, index-friendly).
• Versioning: path prefix (/api/v1) — simple, cache-friendly, explicit.
• Idempotency on unsafe verbs (Day 19/20).

Grading your own APIs

Zoth — RESTful, versioned /api/v1, resources are real nouns. Strong points to cite: status-code discipline (ErrConflict → 409 on transition races; readyz → 503 with per-component latency/error when a dependency is down — that's a contract for the orchestrator); consistent nested error envelope {"error":{"code","message"}}; self-documenting OpenAPI — cmd/apidocgen walks the Chi router and generates openapi.json + a Postman collection, so the spec can't silently drift (though it has: your api.md documents /access-requests/{id}/advisory while the route is /rag-advisory — a live example of why generated specs beat hand-written ones). Weaknesses to own: some mutations are RPC-shaped actions (/approve, /deny, /revoke) — defensible ("state transitions on a resource are verbs; POST /access-requests/{id}/approve is the standard compromise"), and no pagination on audit-logs beyond a limit ≤ 100.

Traverse — the 202/201/200 trichotomy on the same endpoint is textbook async-contract design: 201 created (no AI needed), 202 accepted-for-processing (AI queued), 200 duplicate (idempotency hit, returns the existing submission). That's a contract a client can build on — the extension knows exactly what happened. The notification inbox uses keyset pagination (paged on id), not offset. Error contract: flat {error, code?, field?} with a SAFE_ERRORS allow-list — one shape, no Prisma internals. Weakness to own: validation is mostly hand-rolled in controllers (zod exists but only guards subscriptions).

The rules worth memorizing (then violating knowingly)

1. 404 vs 403 is a security decision, not a style choice. 404-then-403 reveals resource existence to attackers. Traverse's submission endpoints return 404 ("not found") then 403 ("not yours") — an enumeration leak, deliberate per-resource today, fixable by collapsing to 404-for-both (Day 72 covers the full decision). The gold standard for sensitive resources: same body, same timing, 404.
2. Don't leak implementation in errors. Raw Invalid prisma.user.create() invocation: Unique constraint failed… reaching a client = information disclosure. Traverse's resolveError funnels everything unknown to a flat 500.
3. Version before you break, not after. /api/v1 costs nothing on day one; retrofitting it costs a deprecation program.
4. Make retries safe: Idempotency-Key on POST (traverse's idempotencyKey on submissions — literally this pattern), natural idempotency elsewhere (removeOnComplete keyed jobs, ON CONFLICT inserts).

A drill

Design the contract for "approve a request" three ways: (a) POST /requests/{id}/approvals (create an approval resource — auditable, listable, most RESTful), (b) POST /requests/{id}/approve (action-style — what zoth does), (c) PATCH /requests/{id} with {status: "APPROVED"} (least good: the state machine's guardrails vanish into generic PATCH semantics). Being able to argue all three is the skill.