martinholovsky 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:
- 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. - 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). - 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). - 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). - 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. - 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). - Before declaring done, run the relevant files' Audit checklists against your own design as a self-review.
AUDIT mode
When reviewing an existing API:
- Identify the surfaces in scope (REST endpoints, GraphQL schema, protos, WS/SSE handlers, webhook senders/receivers, gateway config) and load the matching rules files.
- 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.
- 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
operationIds, 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 errors), resolver authz, when GraphQL is the wrong choice. |
rules/04-grpc-protocols.md |
gRPC/protobuf work or protocol selection: field-number/reserved evolution rules, deadlines and cancellation propagation, streaming patterns, rich error details, gRPC-Web/Connect, L7 load balancing, REST vs GraphQL vs gRPC decision table. |
rules/05-realtime-websockets-sse.md |
WebSocket/SSE/realtime features: transport choice (WS vs SSE vs WebTransport), upgrade auth & CSWSH, heartbeats, reconnect backoff + resume tokens, ordering/delivery guarantees, backpressure, close codes, SSE replay, pub/sub fanout scaling, presence; WebRTC server hardening (TURN relay abuse, DTLS-SRTP, signaling) when self-hosted. |
rules/06-webhooks.md |
Sending or receiving webhooks: HMAC signing + timestamp + rotation, replay protection, retry/backoff design, ordering caveats, idempotent consumers, outbox dispatch, reconciliation APIs, SSRF defenses for user-supplied URLs. |
rules/07-security-operations.md |
Cross-cutting security/ops on any API: authn scheme selection (keys/OAuth2/mTLS), rate limiting + 429/Retry-After, quotas, request size limits, timeout budgets, CORS, audit logging, multi-tenant isolation, cross-tenant testing. |
Top-10 non-negotiables
- Object-level authorization on every handler — derive tenant/ownership from the credential, never from the request; cross-tenant access returns a consistent 404. (rules/07 §1, §7)
- Never
200 {"error":…}— correct status codes, single RFC 9457 problem+json error shape API-wide, machine-readable codes, trace ID, no internals leaked. (rules/01 §3, §9) - Cursor pagination with enforced max limit on every collection that can grow; stable sort with unique tiebreaker; no unbounded lists in REST or GraphQL. (rules/01 §4, rules/03 §2)
- Idempotency for unsafe operations: Idempotency-Key with stored-response replay on anything that moves money or sends things; webhook consumers dedupe on event ID. (rules/01 §6, rules/06 §4)
- Additive-only evolution, enforced by CI (oasdiff/buf breaking/schema check); clients ignore unknown fields; breaking changes go through the announce→Deprecation/Sunset→measure→410 pipeline. (rules/02)
- Deadlines/timeouts everywhere, outer > inner, propagated and cancellable; long work is async (202 + status resource), never a long-held connection. (rules/04 §3, rules/07 §4)
- Per-principal rate limits + quotas with 429, Retry-After, and RateLimit headers, enforced in a shared store; expensive operations cost-weighted. (rules/07 §2)
- Realtime must resume: heartbeats, jittered reconnect backoff, sequence IDs + bounded replay buffer, explicit resume-failure → snapshot; bounded send queues with a defined slow-consumer policy. (rules/05 §2)
- Webhooks signed and SSRF-proof: HMAC(timestamp + raw body) verified in constant time with replay window; senders block private/metadata IPs with resolve-pin-connect and follow no redirects. (rules/06 §2, §8)
- Proto/GraphQL schema discipline: never reuse a proto field number (reserve removed ones), enum zero = UNSPECIFIED, GraphQL non-null only when guaranteed, every data-touching resolver behind a dataloader. (rules/04 §2, rules/03 §2–3)