apilisted

# API ## Iron Law `DESIGN THE CONTRACT FIRST. EVOLVE WITHOUT BREAKING. PICK STATUS BY ORIGIN.` ## When to Use - Adding, removing, renaming, or reviewing REST endpoints, fields, status codes, webhooks, auth, pagination, rate limits, or idempotency. - Writing or changing OpenAPI, JSON Schema, public SDK boundaries, or integration contracts external callers depend on. ## When NOT to Use - Internal function signatures with no caller contract; use `domain-modeling` or `refactoring`. - Auth, secrets, or trust-boundary review beyond API shape; use `security`. - Database schema design; use `database`. - Non-REST API styles (gRPC, GraphQL, message queues): contract, error, and evolution conventions differ; use `architecture` for style-of-API decisions and the relevant ecosystem's conventions for shape. ## Core Ideas 1. **Contract first.** Sketch OpenAPI or the repo's API contract source before controller code; implement *from* the contract, not toward it. Every response shape is explicit, including errors, empty states, pagination, and auth failures. Durable API interfaces route through `contract-first`; error shape is part of the contract. 2. **Evolution: additive in place; breaking needs a path forward.** Optional fields, query params, headers, methods, and endpoints evolve in place. Renames, removals, required additions, status-code changes, and semantic changes need a successor contract or deprecation path. Never break in place. See