Best practices · Stacks and tools
REST API Design Best Practices
Opens with creditsA language-agnostic guide to REST API design for developers who build HTTP APIs that other teams, apps or customers depend on. It covers resource and URL design, HTTP method semantics, status codes, RFC 9457 error responses, payload conventions, pagination and filtering, idempotency and concurrency control, and versioning, deprecation and documentation with OpenAPI.
Written by Tauseef Fayyaz8 chapters, 31 practicesAbout 20 min31 quiz questionsReviewed 13 October 2026What you will learn
8 chapters · about 20 min
1Resources and URLsHow to model an API as resources and name their URLs so they stay predictable as the API grows.4 practices · 3 min
2HTTP methods and their promisesWhat GET, POST, PUT, PATCH, DELETE and the new QUERY method promise to clients and intermediaries, and how to keep those promises.4 practices · 3 min
- Status codesChoosing status codes that let clients react correctly without parsing the body, and the headers some codes require.4 practices · 3 minOpens with credits
- Error responsesReturning errors in one standard, machine-readable format that clients can handle without special cases.4 practices · 2 minOpens with credits
- Request and response bodiesConventions for JSON payloads that keep an API consistent, unambiguous and easy to extend.4 practices · 2 minOpens with credits
- Pagination, filtering and sortingHow to return large collections in pages that stay fast and correct, and how to let clients filter and sort safely.4 practices · 2 minOpens with credits
- Idempotency, concurrency and cachingMaking retries safe, stopping clients from overwriting each other and letting caches do their job.3 practices · 2 minOpens with credits
- Versioning, deprecation and documentationHow to change an API without breaking the people who depend on it, and how to describe it so they can use it without asking you.4 practices · 3 minOpens with credits
About this guide
REST API design best practices are about the decisions that are expensive to change once someone depends on them. Code behind an API can be rewritten in a weekend. The URLs, status codes, field names and error shapes clients have built against are a contract, and every inconsistency in them becomes a special case in somebody else's code for years.
This guide is language-agnostic: it is about the HTTP interface, not the framework behind it. It starts with resources and URLs, then covers what each HTTP method promises, choosing status codes, returning errors in the standard problem details format, conventions for request and response bodies, pagination, filtering and sorting, making retries safe with idempotency keys and ETags, and finally evolving an API with versioning, deprecation headers and an OpenAPI description.
The advice was checked against the HTTP standards themselves: RFC 9110 for HTTP semantics, RFC 9457 for problem details, RFC 10008 for the new QUERY method (published June 2026), RFC 9745 for the Deprecation header, the IETF Idempotency-Key draft, and the OpenAPI Specification 3.2.1. Server-side implementation concerns such as input validation, logging and rate limiting middleware belong to your framework's own guide.
Common questions
Should I use PUT or PATCH to update a resource?
Use PUT to replace the whole resource: fields you leave out are removed or reset. Use PATCH to change only some fields, ideally with JSON Merge Patch (application/merge-patch+json). Most update forms in apps map to PATCH.
Should validation errors return 400 or 422?
400 fits malformed requests such as invalid JSON. 422 Unprocessable Content fits requests that are well-formed but fail validation rules. Many APIs use 400 for both. Pick one rule, document it and apply it everywhere.
What is the best way to version a REST API?
A version in the path (/v1/), a version header or a media type all work. The important parts are using one scheme for the whole API, versioning only for breaking changes, and announcing retirement with the Deprecation and Sunset headers.
Cursor or offset pagination?
Cursor pagination stays fast on deep pages and does not repeat or skip items when data changes, so use it for feeds, logs and large collections. Offset pagination is simpler and allows jumping to a page number, which suits small admin tables.
What is the standard format for API error responses?
RFC 9457 Problem Details, with the application/problem+json media type and the members type, title, status, detail and instance. It replaced RFC 7807 in July 2023, and most web frameworks support it.
What is the HTTP QUERY method?
A method defined in RFC 10008 (June 2026) that sends a query in the request body while being safe and idempotent, like GET. It suits searches too large or sensitive for a URL. Check that your framework, proxies and clients support it before relying on it.
Sources (8)
Checked against these, last on 13 October 2026.
- RFC 9110: HTTP Semantics, IETFwww.rfc-editor.org/rfc/rfc9110.html
- RFC 9457: Problem Details for HTTP APIs, IETFwww.rfc-editor.org/rfc/rfc9457.html
- RFC 10008: The HTTP QUERY Method, IETFwww.rfc-editor.org/rfc/rfc10008.html
- RFC 9745: The Deprecation HTTP Response Header Field, IETFwww.rfc-editor.org/rfc/rfc9745.html
- RFC 6585: Additional HTTP Status Codes, IETFwww.rfc-editor.org/rfc/rfc6585.html
- RFC 8288: Web Linking, IETFwww.rfc-editor.org/rfc/rfc8288.html
- The Idempotency-Key HTTP Header Field, IETF HTTPAPI Working Groupdatatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/
- OpenAPI Specification v3.2.1, OpenAPI Initiativespec.openapis.org/oas/latest.html
Related on Sefism
Picked from the other libraries by shared topics.
Roadmaps
See allCheat sheets
See allBest practices
See all- TypeScript Best PracticesModern TypeScript best practices for 2026: strict settings, TypeScript 7, modeling data with unions, safe narrowing, runtime validation, generics and typed linting.
- Authentication Best PracticesBuild sign-in that holds up: password rules from NIST, Argon2id hashing, login throttling, MFA and passkeys, secure sessions and safe account recovery.
- Next.js App Router Best PracticesNext.js 16 App Router best practices: Server Components, Cache Components and use cache, secure Server Actions, proxy.ts, metadata and images.
Checklists
See all- Production Readiness ChecklistCheck a service before it takes real traffic: ownership, SLOs, capacity, timeouts and retries, alerts, rollout and rollback, backups, security and on-call.
- API Security ChecklistCheck your REST or GraphQL API against the OWASP API Security Top 10: authentication, object authorization, rate limits, input validation, SSRF, CORS and logging.
- Database Migration ChecklistCheck a schema or data migration before it ships: expand and contract, lock behaviour, online indexes, batched backfills, rehearsal on real data, backups, rollback, deploy order and monitoring.
Project structures
See all- Express with TypeScript project structureFor students who know a bit of JavaScript and want a backend that looks like the ones teams actually run. Express gives you almost no structure, so this layout supplies it: one folder per feature under src/modules, each split into routes, controller, service and repository, with Zod at the edge and Vitest plus Supertest for tests.
- NestJS project structureFor people who want a structured TypeScript backend with clear rules about where code goes. Every feature is a Nest module that owns its controller, service, DTOs, entities and tests, so the app grows by adding folders, not by stretching old ones. The tree follows one orders API from nest new to a codebase a whole team can run for years.
- FastAPI project structureA typed Python API for an orders app, built the way the FastAPI docs and the official full stack template lay it out: one
apppackage, a router per feature, Pydantic schemas at the edges, services in the middle and SQLAlchemy models with Alembic migrations underneath. For students who have finished the FastAPI tutorial and want to know where the second, tenth and fiftieth file go.
Career questions
See all- How do I choose between frontend, backend, mobile, cloud, cybersecurity, data and AI without trying them all for years?Do not try to pick the best field; pick the one whose daily problems you can tolerate on a bad day. Run a short, cheap experiment in two or three candidates, compare what you enjoyed doing rather than what sounded exciting, check the local job market, and commit for six to nine months.
- Should I use Firebase or Supabase for my app?Both let you ship an app fast with auth, a database, storage and hosting-style services. Supabase is built on PostgreSQL, so it suits relational data and SQL skills you will reuse anywhere. Firebase is a mature Google platform with a document database and strong mobile tooling. Choose by your data shape, your platform, and how much you want to learn transferable database skills.
- What should I learn to become a web developer, and in what order?Learn the web platform first (HTML, CSS, JavaScript, how HTTP works), then one frontend framework, then a backend with a database, and build a real project at each stage. If you already know WordPress, you are not starting over: your HTML, CSS and PHP experience transfers.
Stuck on something specific?
Writing only gets you so far. If you want an answer to your situation rather than the general case, book a session and we will work through it together. Sessions are free for approved Sefism members, and a few slots open each week.
- 1:1 Mentorship
- Fresh Graduate Mentorship
- Career Guidance
Brand deals, promos and partnerships: tauseeffayyaz@gmail.com