REST API Design From First Principles
A Complete Guide for Backend Engineers — Interviews + Production
Why This Book Exists
System design teaches you how data moves across machines.
This book teaches you how clients talk to servers — the language, the contracts, the rules.
Every backend engineer gets asked: "Design an API for X."
Most people answer with URLs. The best engineers answer with:
- Why these URLs, not those
- How auth works without sessions
- What happens when the client sends garbage
- How versioning avoids breaking 10,000 mobile apps overnight
- How to make the API fast without the client doing anything
That is what this book builds.
The 10 Chapters
| # | Chapter | Core Question Answered |
|---|---|---|
| 1 | HTTP: The Wire Your API Runs On | What actually happens when a client sends a request? |
| 2 | REST Constraints: Why REST Works | What makes an API RESTful — and why does it matter? |
| 3 | Resource Design: Nouns, Not Verbs | How do you model a domain as URLs? |
| 4 | Request & Response Design | What goes in the body, headers, and status code? |
| 5 | Authentication & Authorization | How does the server know who you are and what you can do? |
| 6 | Error Handling | How do you communicate failure without breaking clients? |
| 7 | Versioning, Pagination & Filtering | How do you evolve an API without breaking existing users? |
| 8 | Performance: Caching & Compression | How do you make APIs fast without changing the client? |
| 9 | API Security | How do you defend against the OWASP API Top 10? |
| 10 | Testing & Documentation | How do you prove your API works and explain it to others? |
Format (Same as Distributed Systems Book)
Each chapter:
- Physical reality first — ground truth before abstractions
- Mechanisms — how it works, step by step
- Design decisions — trade-offs engineers actually face
- Real systems — how Stripe, GitHub, Twilio, etc. solve it
- Vocabulary map — terms defined in a table
- 5 typed practice problems — failure analysis, design, synthesis, go deeper, connect
- What's coming next
Prerequisites
Chapter 1 assumes you know: basic HTTP (GET/POST), what JSON is, what a server is.
That's it. Everything else is built from scratch.
After This Book
You can:
- Design a production REST API for any domain from scratch
- Answer API design questions in any backend interview
- Make informed trade-off decisions on auth, versioning, errors, caching
- Read any API documentation and immediately understand the design choices
Say "chapter 1" to begin.