菜单
Define a schema-first API contract — standardized error envelope (RFC 9457), pagination, status codes, consistent JSON shapes. Use when establishing API conventions, before multiple teams consume an API, or when error responses are inconsistent. Not for choosing the protocol or modeling resources (use api-design) or for runtime input parsing at the boundary (use data-validation).
| name | api-contract |
| description | Define a schema-first API contract — standardized error envelope (RFC 9457), pagination, status codes, consistent JSON shapes. Use when establishing API conventions, before multiple teams consume an API, or when error responses are inconsistent. Not for choosing the protocol or modeling resources (use api-design) or for runtime input parsing at the boundary (use data-validation). |
| license | MIT |
Establish one consistent contract — error envelope, pagination, status codes, JSON shape — so clients can be written against a stable, extensible API and breaking changes are caught before they ship.
Universal — RFC 9457 problem+json, cursor-vs-offset pagination, status-code semantics, and "object-as-root" are HTTP/spec-level conventions that apply to any backend.
Standardize the error envelope (RFC 9457 application/problem+json)
{ type, title, status, detail, instance } + domain extensionsAlways return a top-level JSON object (never a bare array)
{ "items": [...], "nextCursor": "..." } not [...]Pick a pagination strategy and apply it everywhere
Use status codes by their HTTP semantics
200/201/204 success; 400 validation; 401 unauthenticated; 403 unauthorized; 404 not found; 409 conflict; 422 semantic validation; 429 rate-limited; 5xx server4xx = client must change request; 5xx = client may retry429 must include Retry-After (seconds or HTTP-date) — without it clients retry blindly and amplify the storm; rate-limit metadata in RateLimit-* headers (IETF draft) helps well-behaved clients self-throttle4b. Idempotency header for non-idempotent endpoints
Idempotency-Key: <uuid> header on POSTs that create/charge — store key→result so a retried request returns the original result, not a duplicate effect (see resilience-patterns)4c. Optimistic concurrency via ETag / If-Match
ETag: "<version>"; write endpoint requires If-Match: "<version>" and returns 412 Precondition Failed on mismatchSchema-first: generate, don't hand-write
Validate (validation loop)
| ❌ Anti-pattern | ✅ Correct |
|---|---|
| Different error shape per endpoint | One RFC 9457 envelope everywhere |
Bare array response ([...]) | { items: [...], nextCursor } object |
200 OK with { error: "..." } in body | Correct status code (400/409/etc.) |
| Offset pagination on a high-write table | Cursor-based pagination |
| Hand-maintained client types drifting from server | Generate both from one OpenAPI schema |
429 with no Retry-After (clients retry blindly) | Retry-After (+ RateLimit-* headers) on every 429 |
| POST that creates a charge with no idempotency support | Accept Idempotency-Key header; store key→result |
| Last-write-wins on concurrent updates (silent loss) | ETag on read + If-Match on write → 412 on mismatch |
feat(api): add <endpoint> to contract / fix(api): standardize error envelope@nestjs/swagger generates OpenAPI from decorators (code-first)ExceptionFilter mapping to RFC 9457spectral lint openapi.jsonswaggo/swag or hand-written OpenAPI; problem+json middlewareapi-design — choose protocol/resources first, then formalize the contract heredata-validation — the contract's request schema drives boundary validationapplication/problem+json, RFC 9457) and always return a top-level JSON object (never a bare array) so the contract can extend without breaking clients.Build LLM features on the backend — deterministic agent loops (round-trip every tool call by id), RAG over a vector store, token/cost accounting, streaming, eval harness, and prompt-injection defense (treat all model context as untrusted). Use when adding an AI feature, building RAG, or wiring an agent loop. Not for the AI streaming UI on the frontend (use frontend-toolkit's AI integration) or general boundary input parsing (use data-validation).
Choose the API protocol (REST / GraphQL / gRPC) by traffic shape and design resources, versioning, and async patterns. Use when adding a new API surface, designing a service boundary, or when clients complain about over/under-fetching. Not for the schema/error envelope details (use api-contract) or per-resource access control (use authorization).
Default to a modular monolith with enforced internal boundaries; treat microservices as a destination after boundaries prove stable, not a starting point. Use when structuring a backend, when tempted to split into services, or when module boundaries blur. Not for the actual schema-split / service-extraction migrations (use migration-strategy + schema-design).
Build reliable event-driven flows with the Transactional Outbox pattern — write state and event in one transaction, relay asynchronously, achieve at-least-once delivery + consumer idempotency. Use when an action must reliably trigger downstream work, or when events are lost on crash (dual-write problem). Not for simple background work without state+event reliability (use background-jobs) or outbound HTTP webhook specifics (use webhook-design).
Choose and implement auth correctly — JWT vs session vs OAuth decision, pin allowed algorithms server-side, rotate refresh tokens with reuse detection, avoid the classic JWT pitfalls. Use when adding login, integrating OAuth, or when token handling looks risky. Not for access control / permissions (use authorization) or a broader OWASP audit (use backend-security-audit).
Design access control — RBAC for coarse function-level checks, Postgres Row Level Security (RLS) for row-level data isolation, ABAC pushed to the app/policy layer. Use when adding permissions, building multi-user data access, or when one user can see another's data. Not for establishing who the caller is (use authentication) or tenant isolation specifically (use multitenancy-audit).