apilisted

# API ## Iron Law `DEFINE THE CONTRACT FIRST. PRESERVE SHIPPED CALLERS. PICK STATUS BY FAILURE.` ## 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 new or changed caller-visible behavior in OpenAPI or the repo's contract source before controller code, then implement from it. For a fix that restores existing behavior, use the current contract as the source of truth. Make every response shape 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. Preserve shipped contracts with independent callers. Optional fields, params, headers, methods, and endpoints evolve in place when old callers can ignore them. When they alter a shipped contract, renames, removals,