api-designlisted

# API and Interface Design Design stable, well-documented interfaces that are hard to misuse. Good interfaces make the right thing easy and the wrong thing hard. Applies to REST APIs, GraphQL schemas, module boundaries, component props, and any surface where one piece of code talks to another. ## When to use - Designing new REST or GraphQL endpoints - Defining module boundaries or contracts between teams - Creating component prop interfaces or type contracts - Establishing database schema that informs API shape - Changing existing public interfaces - Triggers on "API design", "interface design", "REST", "GraphQL", "contract", "接口设计", "API 契约", "API 设计" **Not for:** system-level architecture decisions (use `architecture`); deep-module or codebase structure (use `codebase-design`). ## Steps ### 1. Define the contract first The contract is the spec — implementation follows. Define typed input and output schemas before writing handlers. The types ARE the documentation. ### 2. Apply core principles **Hyrum's Law:** With enough users, all observable behaviors become de-facto contracts — including undocumented quirks, error text, timing, and ordering. Be intentional about what you expose; don't leak implementation details; plan for deprecation at design time. **The One-Version Rule:** Avoid forcing consumers to choose between multiple versions. Design for a world where only one version exists at a time — extend rather than fork. Multiple versions multiply maintenance cost