The Complete Guide to Building APIs Developers Love

Read before you buy: the PDF here is a free sample — the first 20 pages of the 482-page book (payments, sales and reviews on this demo site are sample data). Get the full e-book at thenexbooks on Gumroad.

Every API is a promise. This book shows you how to make that promise well — with consistent resources, honest status codes, helpful errors, safe retries, and changes that never break your clients.

REST API Design is a practical, opinionated, standards-based guide (RFC 9110, RFC 9457, OpenAPI 3.1 and more) with hundreds of bad → better examples, raw HTTP exchanges, OpenAPI YAML, and FastAPI/Express snippets. One running example — Parcelwise, a shipping and parcel-tracking platform — carries every chapter, from the first endpoint to a complete public API and a v1 → v2 migration.

What's inside (28 chapters + 4 appendices, 482 pages):

Part I — Foundations

• Ch 1 · Why API Design Matters: APIs as Products
• Ch 2 · HTTP Fundamentals for API Designers
• Ch 3 · REST Principles and Constraints — and What Actually Matters
• Ch 4 · Resource Modeling: Nouns, Relationships, and Boundaries
• Ch 5 · URL and Naming Design

Part II — Requests and Responses

• Ch 6 · HTTP Methods: Safe, Idempotent, and Everything in Between
• Ch 7 · Status Codes That Tell the Truth
• Ch 8 · Designing Request and Response Bodies
• Ch 9 · Errors That Help: Problem Details and Validation
• Ch 10 · Headers, Content Negotiation, and Media Types

Part III — Collections and Operations

• Ch 11 · Pagination, Filtering, Sorting, and Search
• Ch 12 · Partial Updates, Bulk Operations, and Batch Requests
• Ch 13 · Idempotency, Concurrency Control, and Safe Retries
• Ch 14 · Long-Running Operations and Asynchronous APIs
• Ch 15 · Webhooks and Event-Driven Integration

Part IV — Contracts, Evolution, and Developer Experience

• Ch 16 · OpenAPI and Design-First Development
• Ch 17 · Versioning and Evolution Without Breaking Clients
• Ch 18 · Documentation, SDKs, and Developer Experience
• Ch 19 · Hypermedia, Links, and Discoverability
• Ch 20 · Designing APIs for AI Agents and Automation

Part V — Security, Performance, and Operations

• Ch 21 · Authentication: API Keys, OAuth 2.0, and OpenID Connect
• Ch 22 · Authorization, Multi-Tenancy, and the OWASP API Security Top 10
• Ch 23 · Rate Limiting, Quotas, and Fair Use
• Ch 24 · Caching and Performance
• Ch 25 · Testing APIs: Contract, Integration, and Consumer-Driven Tests
• Ch 26 · Observability, Governance, and the API Lifecycle

Part VI — Case Studies

• Ch 27 · Case Study: The Parcelwise Public Shipping API
• Ch 28 · Case Study: Evolving a Legacy API to v2

Appendices: A. REST API Cheat Sheet · B. Templates (OpenAPI, Errors, Webhooks) · C. API Design Review Checklist · D. Glossary

Who it's for: backend developers, API designers, tech leads, and architects who build public, partner, or internal HTTP APIs.

Format: PDF (A4), 482 pages, clickable table of contents and bookmarks. Published by thenexbooks.

Book details