メニュー
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).
| name | api-design |
| description | 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). |
| license | MIT |
Pick the right protocol for each API surface by traffic characteristics — not by fashion — and model resources, versioning, and async operations so the contract can evolve without breaking clients.
Universal — protocol selection criteria (latency, client shaping needs, internal vs external), resource modeling, and versioning strategy apply to any language; only the framework's routing/serialization differs.
Choose protocol by traffic shape
Model resources (REST)
/orders/{id} not /getOrder)/orders/{id}/items, not 4 levels)Design versioning before v1 ships
/v1/) — simplest, most visibleAsync / long-running operations
202 Accepted + a status resource (/operations/{id}) for jobs > a few secondsbackground-jobs skillValidate the design
| ❌ Anti-pattern | ✅ Correct |
|---|---|
Verbs in paths (/createUser) | Nouns + HTTP methods (POST /users) |
| GraphQL "because it's modern" for a simple CRUD API | REST default; GraphQL only when field-shaping is a real need |
| Breaking change shipped without a version bump | New version OR additive-only change (see api-contract) |
Deep nesting (/a/{}/b/{}/c/{}) | Max one level; use query params / sub-resource links |
docs/adr/ADR-NNN-api-<surface>.md — protocol choice + rationale + versioning policyfeat(api): design <surface> endpoints [protocol: REST|gRPC|GraphQL]@nestjs/swagger for OpenAPI generation@nestjs/graphql (code-first) + DataLoader for N+1@nestjs/microservices gRPC transport + .proto contractsenableVersioning({ type: VersioningType.URI })api-contract — once protocol is chosen, define the schema-first contract thereschema-design — resource modeling aligns with DB schemaauthorization — per-resource access controlBuild 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).
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).
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).