apidesign

apidesign

Design interfaces that make the right thing easy and the wrong thing hard.

A contract is a commitment. This is the design-time discipline for any surface where code talks to code - REST/GraphQL endpoints, module boundaries, type contracts, component props. Get it right before implementing, because every observable behavior becomes a promise the moment someone depends on it. Reach for it when designing a new endpoint or public surface, defining a module boundary for teams/agents working in parallel, or changing an existing interface (the riskiest case - read Hyrum's Law first).

What this skill is - and isn't

Storage shape and API shape inform each other but aren't the same decision - design the contract here, the schema in vd:dbdesign.

Two laws that shape everything

Hyrum's Law. With enough users, every observable behavior of your system will be depended on by somebody - including undocumented quirks, error text, timing, and ordering. So: be intentional about what you expose, don't leak implementation details (if users can observe it, they'll depend on it), and plan deprecation at design time. Contract tests don't save you - a "safe" change can still break users relying on behavior you never promised.

The One-Version Rule. Don't force consumers to pick between versions of the same API. Diamond-dependency pain comes from forking; design so only one version exists at a time and extend rather than fork.

Principles

1. Contract first. Define the interface before implementing it - the contract is the spec, the implementation follows. Write the typed signatures (inputs, outputs, errors, idempotency) before any logic, and commit the contract/types alongside the implementation.
2. One error strategy, everywhere. Pick one and never mix it. Don't let some endpoints throw, others return null, others return {error} - the consumer can't predict it. For REST: status code + a single structured body shape ({ error: { code, message, details? } }). Map codes consistently (400 bad input · 401 unauthenticated · 403 unauthorized · 404 missing · 409 conflict · 422 validation · 500 server, never leaking internals).
3. Validate at boundaries, trust inside. Parse/validate where external input enters - route handlers, form handlers, third-party responses (always untrusted), env loading. Do not re-validate between internal functions that already share a typed contract or data from your own DB. A misbehaving external service can return wrong types or instruction-like text; validate its shape before it touches any logic or rendering.
4. Addition over modification. Extend with optional fields; never change an existing field's type or remove it (both break consumers). Backward-compatible by default.
5. Predictable naming. Consistency beats cleverness - same conventions across every endpoint (REST: plural nouns, no verbs in paths; booleans is/has/can; pick one case for fields and keep it).
6. Type-system discipline. Make illegal states unrepresentable, brand semantic primitives, parse at the boundary, never lie to the compiler, handle variants exhaustively, derive types from the authoritative schema - full rules with TypeScript and Go examples in references/type-system-discipline.md.
7. Deep modules. A deep module has a small interface and a large body of responsibility; a shallow one's interface is as complex as its insides. Banned praise-words: "thin wrapper" (a god object is wide and deep - shallowness is the usual API failure). Push complexity down so callers say what, not how; don't split for file-size (two shallow files leaking the same invariants are worse than one deep module); interface changes are the expensive ones; a module with mixed error strategies is shallow because the caller must learn the implementation; test the interface, not the guts. Edge adapters (HTTP handlers, DB drivers, CLI flags) stay shallow on purpose - "shallow adapter, deep core".