Best Practices Recap
You now have the full toolkit. Here is the whole course as one checklist you can apply to any API you design or review.
The map
Section titled “The map”flowchart TD Start[Design a REST API] --> R[Resources & URIs] Start --> M[Methods & idempotency] Start --> E[Status & errors] Start --> Q[Querying collections] Start --> VC[Versioning & caching] Start --> Sec[Security] Start --> Ship[Docs, tests, build]
The checklist
Section titled “The checklist”Resources & URIs — model nouns, not actions; plural collections (/articles); lowercase-hyphenated paths; IDs in the path; nest only for ownership, otherwise link. See Resource & URI Design.
Methods & idempotency — map CRUD to GET/POST/PUT/PATCH/DELETE; never mutate on GET; make writes idempotent where you can; protect non-idempotent creates with idempotency keys. See Methods, CRUD & Idempotency.
Status & errors — pick the precise status code; never return 200 for a failure; use one consistent problem+json error shape; return all validation errors at once. See Status Codes & Errors.
Querying collections — always paginate (prefer cursor for large/changing data); allowlist filter/sort fields; offer sparse fieldsets and a consistent envelope. See Querying Collections.
Versioning & caching — favor additive, non-breaking changes; version coarsely when you must; set Cache-Control and ETags; use conditional requests for concurrency. See Versioning & Caching.
Security — HTTPS only; never put secrets in URLs; distinguish 401/403; verify tokens (do not just decode); tight CORS allowlist; rate-limit and validate all input. See Security.
Ship it — describe the API with OpenAPI; test unit/integration/contract layers; keep handlers thin and services HTTP-free. See OpenAPI.