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 | Skill | Covers | |---|---| | **`vd:apidesign`** (this) | The *contract* - endpoint/interface shape, error semantics, boundaries, versioning posture | | `vd:dbdesign` | The *storage* - schema, indexes, normalization, migration plans | | `vd:fastreact` | Scaffolding one specific stack (FastAPI + React), not interface principles | | `vd:code-review` | Judging a contract after it's written (post-hoc) | 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...