api-design

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 and create diamond dependency problems.

Addition Over Modification: Extend interfaces without breaking consumers — add optional fields, never change existing field types or remove fields. Breaking changes without versioning break consumers.

3. Pick one error strategy and use it everywhere

Every error response follows the same shape. Don't mix patterns — if some endpoints throw, others return null, and others return { error }, the consumer can't predict behavior.

interface APIError {
  error: {
    code: string;        // Machine-readable: "VALIDATION_ERROR"
    message: string;     // Human-readable: "Email is required"
    details?: unknown;   // Additional context when helpful
  };
}