apidesign

Topics in the source

• apidesign
• What this skill is - and isn't
• Two laws that shape everything
• Principles
• REST shape (worked patterns)
• Typed-contract patterns (TS as the worked example; the ideas are language-agnostic)
• Red flags
• Integration points

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). | 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. Hyrum's Law. With enough users, every observable behavior of your system will be depended on by so

This is an excerpt. Refer to the complete source and its current requirements.