sota-api-designlisted

# SOTA API Design & Audit ## Purpose Expert-level rules for building and auditing API surfaces: HTTP/REST semantics, GraphQL, gRPC/protobuf, realtime (WebSocket/SSE/WebTransport), webhooks, contract evolution, and the security/operational envelope around all of them. Rules are imperative with rationale and good/bad examples; every rules file ends with an audit checklist. Use the index table below to load only the files relevant to the task — do not read all files for a narrow question. ## BUILD mode When designing or implementing an API: 1. **Pick the protocol deliberately.** Read `rules/04` §1 first if the choice (REST vs GraphQL vs gRPC vs realtime transport) is open. Default: gRPC service-to-service, REST at the edge, GraphQL only for multi-client shape diversity, SSE for server-push, WS only for true bidirectional. 2. **Contract first.** Write the OpenAPI/SDL/proto before handlers. Get the resource model, error shape (RFC 9457), pagination, and naming right in the spec — they are nearly impossible to fix later (`rules/01`, `rules/02`). 3. **Design for a decade of additive change.** String enums not booleans, RFC 3339 timestamps, opaque IDs, open enums, tolerant-reader contract, CI breaking-change diff from day one (`rules/02`). 4. **Build the unhappy paths with the happy path**: idempotency keys, 429 + Retry-After, timeout budgets, problem+json errors, size limits — these are features, not hardening passes (`rules/01` §6, `rules/07`). 5. **