A practical reference for designing, building, and documenting production-grade REST APIs with Node.js and Express.
This is not a beginner guide to what an API is. It is a reference for developers who are already building APIs and want to do it well — consistently, defensibly, and in a way that does not create problems for the people consuming them.
Every section covers the reasoning behind a decision, not just the decision itself. Where the industry has a clear standard (OpenAPI, RFC specifications, OWASP), that standard is cited. Where there is genuine trade-off between approaches, both sides are stated.
The code examples throughout use Express and Node.js with TypeScript.
| Audience | How to use this |
|---|---|
| Backend developers building their first production API | Read in order — each section builds on the last |
| Developers inheriting an existing API and trying to improve it | Jump to the sections covering the problems you are facing |
| Teams establishing shared API conventions | Use individual sections as the basis for internal engineering decisions |
| Frontend developers who want to understand what makes an API easy to consume | Sections 2, 4, 5, and 6 are particularly relevant |
| # | Section | Summary |
|---|---|---|
| 1 | REST Fundamentals | What REST actually is, constraints, resource modeling, HTTP semantics |
| 2 | Request & Response Design | Consistent response shapes, status codes, naming conventions |
| 3 | Error Handling | Error response standards, operational vs programmer errors, client-friendly messages |
| 4 | Versioning | URL vs header versioning, when to version, backwards compatibility |
| 5 | Pagination, Filtering & Sorting | Cursor vs offset pagination, filter conventions, sort parameters |
| 6 | Idempotency | What idempotency is, idempotency keys, safe retries |
| 7 | Authentication & Authorization in APIs | JWT in APIs, API keys, scopes, per-endpoint authorization |
| 8 | Validation | Input validation with Zod, schema-first validation, sanitization |
| 9 | Rate Limiting & Throttling | Rate limit strategies, headers, response format, Redis-backed limiting |
| 10 | OpenAPI Specification | Writing OpenAPI 3.1 specs, code-first vs spec-first, tooling |
| 11 | Testing APIs | Integration testing with Supertest, contract testing, test structure |
| 12 | Security | OWASP API Security Top 10, headers, CORS, injection prevention |
| 13 | Reference Library | All books and resources cited throughout this guide |
Each section includes working Express/TypeScript code examples, the reasoning behind each decision, and explicit trade-offs.
If you are designing a new API from scratch, read Sections 1 through 6 before writing any code. These cover the decisions that are expensive to change later — resource naming, response shape, versioning strategy, and error format.
If you are improving an existing API, each section is self-contained. You can jump to the problem you are trying to solve. Section 3 (Error Handling) and Section 5 (Pagination) are the most commonly neglected areas in APIs that have grown organically.
If you are writing an OpenAPI spec for the first time, read Section 2 and Section 3 first so you understand what you are documenting, then move to Section 10.
This guide is part of a series on engineering and product development:
- Product Development Playbook — The complete 17-phase guide from idea to launch
- PERN Stack Architecture Guide — Clean architecture, layering, and project structure for PERN apps
- System Design for Web Developers — A practical system design reference for developers who build real products
This guide draws from:
- Books: The Design of Web APIs (Lauret), RESTful Web APIs (Richardson & Amundsen), HTTP: The Definitive Guide (Gourley et al.), and others — all cited inline
- Standards: OWASP API Security Top 10, OpenAPI 3.1 Specification, RFC 7231 (HTTP Semantics), RFC 7807 (Problem Details), RFC 9457 (Problem Details — updated)
- Engineering resources: Stripe API documentation, GitHub API documentation, Google API Design Guide
The full list is in Section 13 — Reference Library.
See CONTRIBUTING.md for guidelines on fixing errors, adding references, or suggesting new sections.
MIT License — free to use, adapt, and distribute. See LICENSE.
Kuril
A dreamer… who still working on it to make it real.
If this guide helped you, consider giving it a ⭐ — it helps others find it too.