principle-api-designlisted

# API Design An API is a contract. Breaking it breaks callers. Design for evolvability from day one. ## Contract-First Design the interface before the implementation. Write the schema or proto before any code. - Contracts force clarity on resource modeling, field names, and error cases early. - If the design is painful to describe, the implementation will be painful to use. - API review at design time is cheap; API review after clients exist is very expensive. ## Versioning Every breaking change requires a new version. Communicate it, window it, enforce the schedule. - **Breaking:** removing a field, changing a field type, changing semantics of a status code, renaming a resource. - **Additive (non-breaking):** new optional fields, new endpoints, new enum values in response. - **URL-path versioning** (`/v1/orders`) — visible, cacheable, easy to route; good for major versions. - **Header versioning** (`API-Version: 2024-01-01`) — cleaner URLs; common for date-based schemes. - Set a deprecation window (minimum 6 months for external APIs) and enforce it; sunset headers signal the date. ## Idempotency Operations must be safe to retry. Network failures happen; callers will retry. - **Safe** (GET, HEAD, OPTIONS) — no side effects. - **Idempotent** (PUT, DELETE) — repeating produces the same result. - **Non-idempotent** (POST) — accept an idempotency key header; server deduplicates by key. - Key scope: client-generated UUID, tied to the logical operation, expires after a defin