Designing REST APIs

Workflow: Designing a new API

1. Model resources as nouns. Identify domain entities. Use plural nouns for collection URLs (/orders, not /getOrders). Express relationships with sub-resources, max 2–3 levels deep.
2. Assign HTTP methods by semantics. GET=read, POST=create, PUT=full replace, PATCH=partial update, DELETE=remove. For non-CRUD actions, use POST with a clear resource name (POST /orders/7/cancellation).
3. Define request/response schemas. Use camelCase for JSON fields, UPPER_SNAKE_CASE for enums, RFC 3339 for dates in UTC. Wrap collections in { "data": [...] }. Use string type for IDs. Represent money as smallest currency unit + currency code.
4. Select status codes. Return the most specific code: 201 for creation (with Location header), 204 for no-content success, 409 for conflicts, 422 for business rule violations. Never return 200 with an error body.
5. Design error responses using RFC 9457 (Problem Details). Include type (URI), title, status, detail. Return all validation errors at once. Never leak stack traces.
6. Add pagination to every list endpoint. Default: cursor-based pagination. Use offset pagination only for small/static datasets needing jump-to-page. Always include has_more or a next link.
7. Plan versioning. Use URI path versioning (/v1/). Only bump for breaking changes. Support at least one prior version with 6–12 month migration window. Signal deprecation via Deprecation and Sunset headers.
8. Address cross-cutting concerns. Add rate limiting headers on every response. Use Cache-Control + ETags. Require idempotency keys for POST endpoints with side effects. Use Authorization: Bearer for auth.
9. Write the OpenAPI spec first (design-first, not code-first). Use OpenAPI 3.1. Document every endpoint, every status code, every error type. Lint with Spectral or Redocly CLI.

Workflow: Adopting API-first process

1. Identify consumers. List every team and system that will call the API before designing anything. If consumers aren't in the room, the API will be optimized for the producer.
2. Run a design session. Start from the consumer's workflow, not the data model. Sketch endpoints and payloads informally before writing YAML. Name disagreements immediately — they're cheap to resolve now, expensive later.
3. Write the spec first. Formalize the agreed design as an OpenAPI spec. Review it via PR with automated linting, consumer sign-off, and breaking change detection. Change the spec first, then the implementation — never the reverse.
4. Generate mocks immediately. Unblock consumers with a mock server (Prism, Postman Mock Server) the moment the spec is agreed. Consumers build against the mock while the backend builds against the same spec.
5. Enforce the contract in CI/CD. Lint specs on every PR. Detect breaking changes before merge. Validate implementation responses against the spec. Run consumer contract tests. Automate all of this — process discipline alone erodes under deadline pressure.
6. Govern lightly. Maintain an API catalog tracking each API's lifecycle stage (draft → active → deprecated → retired). Signal deprecation via Deprecation and Sunset headers with a migration guide and sunset date.
7. Design for AI-agent consumers. Write description fields as if explaining to a non-expert. Provide example values for every field. Use clear operationId values. A complete, well-described OpenAPI spec is nearly MCP-compatible for free.

For detailed guidance: references 09–11.

Workflow: Reviewing an existing API

1. Check resource modeling. Flag verb-based URLs, deep nesting (>3 levels), inconsistent pluralization, trailing slashes, or file extensions in URLs.
2. Check HTTP method usage. Flag GET with side effects, POST used for retrieval, PUT used for partial updates, missing Location header on 201 responses.
3. Check error handling. Flag custom error formats (should use RFC 9457), 200 with error bodies, leaked internals, one-error-at-a-time validation.
4. Check pagination. Flag unbounded list endpoints, offset pagination on large datasets, missing has_more/next indicators.
5. Check security. Verify HTTPS-only, object-level authorization (not just endpoint-level), input validation, rate limiting, CORS whitelist (no * on authenticated endpoints).
6. Check naming consistency. Flag mixed casing conventions, nullable booleans (should be enums), integer enum values (should be strings), bare array responses.
7. Report findings grouped by severity (breaking issues → best practice violations → suggestions).

Key decisions (defaults with escape hatches)

Decision	Default	Alternative (when)
Pagination	Cursor-based	Offset — small/static data needing page numbers
Partial update	PATCH with JSON Merge Patch (RFC 7396)	JSON Patch (RFC 6902) — need array ops or conditional updates
Versioning	URI path (/v1/)	Content negotiation — per-resource granularity needed
Auth	OAuth 2.0 + JWT (RS256, 15–30 min TTL)	API keys — simple server-to-server; mTLS — service mesh
Async pattern	202 Accepted + status polling	Webhooks — server-to-server event-driven
Upload method	Multipart form data (1–100 MB)	Presigned URLs — cloud-native; Resumable — >100 MB
Error format	RFC 9457 (Problem Details)	— (no alternative; this is the standard)
Rate limiting	Token bucket	Sliding window — smoother enforcement
JSON casing	camelCase	snake_case — Python/Ruby-centric ecosystem

Reference material

Consult these for detailed guidance, examples, and tradeoff analysis:

• 01 — Resource & URL design, Statelessness
• 02 — Naming conventions, Schema design, HTTP methods
• 03 — Status codes, Error handling (RFC 9457)
• 04 — Versioning, Pagination, Filtering & sorting
• 05 — Bulk & batch operations, Async & long-running operations
• 06 — File uploads & binary data
• 07 — Security (OWASP Top 10), Authentication & authorization, Rate limiting
• 08 — Caching (ETags, Cache-Control), Idempotency, Content negotiation
• 09 — HATEOAS, OpenAPI documentation, Observability, Testing
• 10 — Evolution & deprecation, API-first process, Governance
• 11 — AI-agent consumers (MCP), Organizational adoption, Tooling reference