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.

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.

When to use

• Designing new endpoints or a service's public surface.
• Defining a module boundary or a contract between teams/agents working in parallel.
• Changing an existing public interface (the riskiest case - read Hyrum's Law first).

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.
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. Small interface, large responsibility. Push complexity down; do not split for file-size. Vocabulary and banned praise-words: references/deep-modules.md.