Description
Anyone can make an endpoint return JSON. Designing an API that other engineers can use without asking you what it does, that survives being changed without breaking every client, and that holds up under real load and real attackers, is a different skill. Most REST APIs are a pile of endpoints that each made sense alone and contradict each other together: inconsistent naming, status codes that lie, errors a client cannot parse, no pagination until the list has ten thousand rows, auth bolted on at the end, and a breaking change shipped without a version. The HTTP and JSON are the easy part. The design, the consistency, and the contract you are committing to are the part that decides whether your API is a pleasure or a liability.
This book teaches you to design REST APIs as a contract other engineers depend on, not a pile of endpoints that each made local sense. It starts from REST as a model (resources, not actions, and what that buys you) and builds the design judgment that makes an API predictable: modeling resources and their relationships, using HTTP methods and status codes for what they actually mean, naming and structuring URLs so a developer can guess the next endpoint, and returning errors a client can actually handle. Then it covers the parts that separate a toy from a production API: pagination, filtering, and sorting that do not fall over on a big collection, validating input and never trusting the client, authentication and authorization done right (tokens, scopes, and not leaking data across users), idempotency so a retried request does not double-charge, and rate limiting and caching so the API stays up. The hardest chapters are about the contract over time: versioning without breaking every client, evolving an API by adding rather than changing, documenting it so people do not have to read your code, and the discipline that a public endpoint is a promise you have to keep. The examples are a real API, shown designed badly and then well. For backend engineers who want to build an API other people are glad to use and that they do not have to rewrite in a year.
Is this book for you?
This book is for: backend engineers who can make an endpoint return JSON and now have to design an API that other teams build on, version without breaking, and keep fast and safe under real traffic.
The shortcut nobody hands you
The 4 Steps to Becoming the Engineer Other Teams Depend On. The method for designing a REST API other engineers treat as a contract they can trust, not a pile of endpoints they have to reverse-engineer. You build it in load-bearing layers, so a developer can guess your next endpoint without reading your mind, it holds up under real traffic and real attackers, and you can change it for years without breaking a single client. Go from a wall of endpoints nobody agrees on to an API a partner integrates in one afternoon.
- Model what the API is made of
- Make the surface predictable to guess
- Harden it for real traffic and attackers
- Change it for years without breaking clients
Every chapter, laid out
- Chapter 1: The engineer who couldn’t tell which endpoint to trust
- Chapter 2: Forty endpoints, and no two clients agree which to call
- Chapter 3: Get the nouns wrong and you’ll apologize in the docs for a year
- Chapter 4: The 200 OK that made the spinner run forever
- Chapter 5: URLs a developer can guess without opening your docs
- Chapter 6: Half of using your API is the moment it says no
- Chapter 7: Green on every test, down at a million rows
- Chapter 8: The user who made themselves an admin with one extra field
- Chapter 9: Change one digit in the URL and read another company’s data
- Chapter 10: Assume every request will arrive twice
- Chapter 11: Changing a contract while people are standing on it
- Chapter 12: Your API works, but nobody can find how to use it
- Chapter 13: The API a partner integrates in a single afternoon
