/sota-api-design

name: sota-api-design
description: >-
  State-of-the-art API design and audit guidance (2026) covering REST/HTTP,
  GraphQL, gRPC, WebSockets/SSE/realtime, webhooks, versioning/evolution, and
  API security/operations. Use when designing or building any API surface
  (endpoints, schemas, protos, realtime channels, webhook senders/receivers)
  AND when auditing/reviewing existing APIs for correctness, evolvability,
  security, and operational robustness. Not for browser UI, rendering, or
  client-framework concerns — use sota-web-frameworks or sota-frontend-design.
  Trigger keywords: API, REST, GraphQL,
  gRPC, endpoint, websocket, SSE, realtime, WebRTC, webhook, versioning, OpenAPI,
  pagination, idempotency, rate limit, problem+json, protobuf, deprecation.

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. **Realtime and webhooks are protocols, not endpoints.** Specify auth, heartbeat, resume, ordering, backpressure, and close semantics (`rules/05`); signing, retries, SSRF egress controls (`rules/06`) before writing code. 6. **Security envelope is part of the design**: authn scheme per consumer type, per-principal rate limits, tenant isolation derived from credentials, audit logging (`rules/07`). 7. Before declaring done, run the relevant files' **Audit checklists** against your own design as a self-review.

AUDIT mode

When reviewing an existing API:

1. Identify the surfaces in scope (REST endpoints, GraphQL schema, protos, WS/SSE handlers, webhook senders/receivers, gateway config) and load the matching rules files. 2. Work through each file's **Audit checklist** against the actual code/spec — verify in code, don't trust docs or comments. Prefer reading: route definitions, middleware chains, error handlers, pagination queries, proto history, WS connection handlers, webhook dispatch code, gateway/limiter config. 3. Actively probe the classic gaps: missing object-level authz (BOLA), offset pagination on big tables, `200 {"error":…}`, missing deadlines, unbounded WS send buffers, unsigned webhooks, SSRF in webhook egress, origin-reflection CORS, tenant ID taken from the request body.

Severity conventions

• **Critical** — exploitable security flaw or guaranteed data corruption/loss:

missing object-level/tenant authz, unsigned or non-constant-time-verified webhooks, SSRF-able webhook egress, credential leakage (query strings/logs), origin-reflection CORS with credentials, reused proto field numbers, double-execution of payments (no idempotency on money writes).

• **High** — breaks clients or production under normal conditions: breaking

change shipped without versioning/deprecation, no rate limiting on authed surface, missing deadlines/timeout hierarchy, unbounded pagination or request sizes, no WS backpressure/resume (silent data gaps), non-idempotent webhook consumers.

• **Medium** — erodes the contract or operability: wrong status codes, non-RFC

9457 error sprawl, offset pagination at scale, spec/implementation drift, no Sunset/Deprecation signaling, missing rate-limit headers, N+1 resolvers, closed response enums.

• **Low** — polish and convention: naming inconsistency, missing `operationId`s,

missing preflight cache, suboptimal cache headers, missing pagination link hints.

Finding format

[SEVERITY] <one-line title>
Where: <file:line | endpoint | schema element>
Rule: <rules-file §section>
Issue: <what is wrong, with the observed evidence (code/HTTP exchange)>
Impact: <concrete consequence — who breaks, what leaks, what corrupts>
Fix: <specific change; example snippet/header/schema where load-bearing>

Order findings by severity; one finding per root cause; no speculative findings without evidence in code or spec.

Rules index

| File | Read this when... | |---|---| | `rules/01-rest-http-design.md` | Designing/auditing REST endpoints: resource modeling, methods/status codes, cursor pagination, filtering, partial responses, idempotency keys, ETags/conditional requests, HATEOAS pragmatism, RFC 9457 errors, OpenAPI-first, contract testing. | | `rules/02-versioning-evolution.md` | Changing an existing API, adding/removing fields, choosing URL vs header versioning, planning deprecation (Sunset/Deprecation headers), enum/schema evolution, tolerant readers, CI breaking-change gates. | | `rules/03-graphql.md` | Any GraphQL work: schema/nullability/connections design, N+1 and dataloaders, depth/cost/alias limits, persisted-query allowlists, error channels (userErrors vs err