The complete method for designing clear web APIs from the point of view of whoever consumes them.
Why this book
We all learn to consume APIs before we ever design one. And the day we ship one, it shows: a field named sts, a homemade date format, an operation that dumps a database table as-is. The consumer struggles, swears, and ends up writing three functions to undo our choices. Designing an API isn't something you improvise, and that's exactly what almost nobody taught us.
Arnaud Lauret, a French author known as the "API Handyman", wrote the missing book. This 2nd edition from 2025 takes a subject usually handled by gut feeling and turns it into a method, from the business need all the way to the OpenAPI document. The thread isn't the technology, it's an obsession: everything is designed from the point of view of whoever will consume the API, never from the one who implements it.
The ideas that stick
The book runs nearly 580 pages across three parts. Here is what stays with you once it's closed.
1The Kitchen Radar: design for whoever uses it
Lauret opens on a microwave renamed "Kitchen Radar", whose only control is a "MAG." button you hold down with precise timing to dose the magnetron's power. To reheat your soup, you must become a magnetron expert. "The inside-out interface forces users to become magnetron experts." That's exactly what most APIs do: they expose their internal machinery instead of what the user wants to do.
The rule that runs through the whole book: you design from the consumer's point of view. People don't want to "turn on the magnetron", they want to "heat a dish". A good API is the restaurant waiter who hides the kitchen, not the chef shouting the recipe at you.
2Recipes and ingredients: decide WHAT before HOW
Before choosing a single URL or HTTP verb, Lauret has you list, in plain language, what users want to accomplish. His method fits in a table, the "API Capabilities Canvas": user, use case, step, input, success, failure, operation.
His phrase: "use cases are like recipes, and operations are their generic ingredients." A well-thought operation is generic ("heat food at a given power and time"), not specific ("heat milk and chocolate"). Separating the WHAT (the capabilities, in plain words) from the HOW (REST, HTTP) keeps implementation reflexes from warping the design from the very start.
3Your API is not your database
The most common sin: mirroring the database into the API. A column named CUSD, a table returned as-is, a supplier.phone exposed just because it happens to be stored.
Lauret's rule: the data you exchange is a representation, not a copy of your storage. "Focus on the data exchanged from a subject matter perspective rather than on storage." Names, types, structure can all differ between the API and the database; the implementation does the translation. The consumer should see a clear field like overdraftFacility: active, never a raw column name like CUSD or the schema of your tables.
4The "wow" effect: predictable names give superpowers
A good name lets a developer guess the rest. Lauret puts it this way: "an intuitive API design gives developers superpowers, allowing them to guess available data and operations." He walks through cleaning up a real banking field: ACTBLNDFPRTFTBKACC becomes, step by step, overdraftFacility.active.
And being interoperable means reusing existing standards instead of inventing your own:
- IBAN for an account;
- ISO 8601 for a date (
1982-12-20T10:31:00Zinstead of an unreadable Unix timestamp); - GeoJSON for coordinates.
A developer who already knows the standard has zero documentation to read. The contrast lives in one JSON response:
// ✗ guessed by nobody // ✓ guessed by everyone, and standard
{ "ACTBLNDFPRTFTBKACC": true, { "overdraftFacility": { "active": true },
"dt": 1671531060 } "createdAt": "1982-12-20T10:31:00Z" }5Errors: be generous, say everything at once
An empty 400 Bad Request is a slap. A useful error says what's wrong, where, and what's accepted. Above all, it returns ALL the problems at once, not one per round-trip: you don't make the consumer fix, resend, discover the next error, repeat.
// ✗ 400 Bad Request (empty: the consumer has to guess)
// ✓ 400 + application/problem+json: EVERYTHING, at once
{ "type": "validation-error",
"errors": [
{ "field": "email", "issue": "invalid format" },
{ "field": "age", "issue": "must be >= 18" }
] }Lauret leans on Postel's law (be liberal in what you accept, strict in what you send) and on the RFC 9457 standard (application/problem+json), so that error formats are predictable from one API to the next. An error should help you solve the problem, not just report it.
6The safest data is the data that doesn't exist
The designer can't solve every security problem, but they decide the exposed surface. "The most secure data or operation is the one that doesn't exist." Three ways to apply it:
- don't expose it at all;
- mask it (4444 instead of the real card number);
- hide it behind a permission.
And a warning that surprises everyone: HTTPS does NOT protect everything. It encrypts the wire, but the data ends up in logs, passes through intermediaries, and lands on uncontrolled devices (your own banking app runs on the customer's phone).
Consequence: never put sensitive data in a URL, because URLs get logged. And "opacity isn't security": an unreadable identifier is not an access control.
7The most efficient API call is the one that doesn't happen
A dashboard that fires 100 parallel calls and takes up to 11 seconds becomes a single GET /dashboard call in 100 milliseconds, simply by stopping delegating the assembly to the consumer. "The most efficient API call is the one that doesn't occur."
But Lauret is refreshingly honest: most performance problems he's seen had nothing to do with the design. "The most predominant cause was databases; I can't count how often the solution was to add a missing database index." Measure the real cause before adding complexity to the API.
8Change without breaking: stay on v1 as long as you can
Once an API has consumers, every change risks breaking them. Lauret maps the two camps:
- safe: adding an optional field, widening a limit;
- breaking: renaming, removing, making a field required.
He invokes Hyrum's Law: with enough users, every observable behavior of your API will end up being relied on by someone, documented or not. His advice runs against the "let's go to version 2" reflex: stay on version 1 as long as possible, and only break everything if it's truly worth the cost.
And design for extension from day one. The boolean is a trap: it has only two states, and the 3rd case forces you to rename it (breaking). The enum leaves the door open:
// ✗ binary: the day "pending" appears, executed no longer fits
{ "executed": true }
// ✓ extensible: adding a value breaks no client
{ "status": "executed" } // then "pending", "cancelled"…Three things I didn't know
- The whole book runs on three fictional APIs followed from start to finish: a social network, an online shop and a bank. So every principle has the same concrete example coming back, and you watch the same API transform across chapters. It's repetitive, but it anchors.
- Lauret designs "design-first": you write the OpenAPI spec WHILE designing, as a thinking tool, not as documentation written afterward. And then you run it through a linter (Spectral) exactly like you lint code, to enforce the rules automatically. He still warns: don't start the OpenAPI too early, it forces premature REST thinking.
- On governance he has a line: API rules should be an enabler, not "the API police yelling at people who don't follow the rules". And on AI (new in this 2025 edition): learn the fundamentals before depending on AI, "as AI can produce wrong, inaccurate, or incomplete responses".
My take, honestly
This is the book that turns API design from something you fudge by feel into a real craft you can teach. The "consumer's point of view" discipline, the rule never to expose your database, the recipes-and-ingredients method: I haven't seen it anywhere else laid out this clearly. And the metaphors land, the dumb microwave, the restaurant waiter: you remember them.
What weighs it down is the format. Nearly 580 pages, and a method systematic to the point of exhaustion. Part one walks you through identify, observe, represent, model, describe, on the SAME shop example, for six chapters. The examples are excellent, but they march on relentlessly. It's a reference manual, not a book you devour. You read it with the keyboard next to you, or you dip into it when you need to.
Still, Lauret never oversells. He admits most performance issues came from a missing database index, not the API. He advises staying on v1 "forever" if it suffices. He refuses to push GraphQL by default. And this edition is genuinely current: OpenAPI 3.1, RFC 9457 for errors, HTTP/2, even AI. On a topic where most resources are dated, that's precious.
Odilon
Still relevant in 2026?
More than ever, and for a timely reason. APIs are no longer consumed only by humans and their apps: they're consumed by AI agents, handed "tools" to call. And an agent has exactly the same needs as a human developer, only worse: a predictable, well-named, self-describing API. Everything this book teaches you to do for a developer's "wow" is precisely what lets an LLM call the right endpoint with the right parameters. Lauret saw it coming in this edition. His obsession with the consumer's point of view extends naturally to a consumer that isn't human.
Who is it for?
Read it if
- You design or maintain REST APIs and you mostly do it by feel
- You're sick of APIs that spit out the database as-is
- You want a repeatable method, from the business need to the OpenAPI document
- You're setting up API rules or governance in a team
Skip it if
- You want a quick "an API in one hour" tutorial: this is a full method, not a quickstart
- You do GraphQL or gRPC exclusively: the book is REST/HTTP-centric, even if it opens up at the end
- You want pure concept: this is a hands-on, very systematic, sometimes repetitive manual
Going further
The ideas in this book carry into my free courses: building and shipping a real service in the deployment course, and the art of reviewing what a machine produces in Coding with AI, where a clear API becomes exactly the contract an agent can follow without getting it wrong.
More book notes coming: one book at a time, the marrow only.
Comments (0)