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`. - Auth, secrets, or trust-boundary review beyond API shape; use `security`. - Database schema; use `database`. - gRPC, GraphQL, or message-queue APIs: use `architecture` for the style decision and that ecosystem's conventions for shape. ## Rules 1. Sketch the contract (OpenAPI or the repo's contract source) before controller code and implement from it. Every response shape is explicit, including errors, empty states, pagination, and auth failures. Durable API interfaces route through `contract-first`. Additive changes old callers cannot notice (a new optional field, param, or endpoint) proceed without a stop; state the shape in the close-out. 2. Never break in place. Optional fields, params, headers, methods, and endpoints evolve in place. Renames, removals, required additions, status-code changes, and semantic changes need a successor contract or a deprecation path with an overlap window. One versioning strategy per service, applied consistently; compatible additions never re-v