API Design

Coverage

Design clear and evolvable API surfaces. Covers resources vs actions, route naming, request/response schemas, validation, status codes, pagination, filtering, sorting, idempotency, auth boundaries, error envelopes, rate-limit signals, versioning, deprecation, and contract examples.

Philosophy

An API is a product surface for another program. Its main job is stable meaning under change. Internal convenience should not leak into routes, schemas, or errors unless consumers actually need it.

Prefer boring consistency. A small set of predictable patterns beats clever endpoint-specific behavior that every client has to rediscover.

Method