Designing Web APIs: reading a client's API the way its designers saw it

The 11-chapter table of contents of Designing Web APIs starts with “What’s an API?”, moves through security and design best practices, turns to Scaling APIs in chapter 6, and then covers managing change and developer programs. A large part of the book is therefore about what happens once an API has real users.

For a Forward Deployed Engineer, that is the part worth paying for. You will rarely design an API from scratch. Far more often you sit in front of a client’s API that has passed through three generations of teams, and you have to connect your system to it before the demo deadline.

The book is written for the other side: the people who build and run APIs. Read from the integrator’s side, it helps you understand why a client’s API looks the way it does, and predict where it will break.

What is this book?

The full title is Designing Web APIs: Building APIs That Developers Love, by Brenda Jin, Saurabh Sahni and Amir Shevat, published by O’Reilly Media in 2018. The paperback (ISBN 9781492026921) runs to 232 pages; some library records give a different page count depending on the edition. It is aimed at developers, architects and tech leads.

The book’s own description admits that building a widely used API, along with a thriving developer ecosystem, is very hard. It includes hands-on exercises for building an API and running it in production, plus worksheets, checklists and case studies from Slack, Stripe, Facebook, Microsoft, Cloudinary, Oracle and GitHub. Appendix A is titled API Design Worksheets.

Because it came out in 2018, treat it as a book about how to think, not as a tooling reference. The way you frame questions when designing an API changes far more slowly than the tools do.

Why should integrators read a book for designers?

Every API you meet at a client site is the trace of a chain of decisions. Someone once picked a paradigm, chose a security model, set load limits, and then had to change the API without breaking existing clients. The book’s table of contents walks through exactly those stages: paradigms, security, scaling, managing change.

Once you know what the designer had to weigh at each stage, you read the client’s API documentation differently. You stop asking only which endpoint returns which data. You start asking what trade-offs they made, and where the cost of those trade-offs will land on your integration.

Three ideas to take to a client site

First, the paradigm explains the shape of the API. The book puts the API Paradigms chapter straight after the chapter defining an API, and one of the goals it sets out is distinguishing request-response APIs from event-driven ones, including WebHooks and WebSockets.

At a client site, identifying the style correctly from the start keeps you from forcing a familiar model onto a system built on different logic.

Second, scaling is a number you have to work out in advance. Chapter 6 has dedicated sections on Paginating APIs and Rate-Limiting APIs. Imagine a client needs to sync 50,000 orders, the API returns 100 records per page and allows 60 requests per minute: that is 500 requests, about 8 minutes 20 seconds for one full run.

That is the best case. If 5% of requests fail and have to be rerun, you add 25 requests, about 25 more seconds, and every retry eats into the same quota meant for new requests. Now change the parameters yourself and watch the numbers move:

Hypothetical scenario	Requests	Minimum time
100-record pages, 60 requests/min	500	8 min 20 s
1,000-record pages, 60 requests/min	50	50 s
100-record pages, 10 requests/min	500	50 min
100-record pages, 10 requests/min, 5% retries	525	52 min 30 s

The lesson is in the third row. For the same volume of data, a tighter quota alone is enough to make a promise of “near real time” evaporate. Larger pages cut the time, but each response is heavier and a single failure means reloading more data. You need to know this before the demo, not during it.

Third, every API version change is a chance for the integration to break. The book has a chapter devoted to managing change, and its exercises go as far as running an API in production. For an FDE, reading the client’s versioning history and deprecation policy should be a first-week task.

Common integrator mistakes

The most common mistake is estimating sync time and forgetting retries. Failed requests still count against the same quota, so a hasty rerun can push a job into a loop of being throttled, where each retry makes it slower.

The second is assuming every API is REST. If the client pushes data through WebHooks or WebSockets, your architecture has to receive events rather than poll. Get this question wrong and the whole adapter layer has to be rewritten.

The third is treating authentication and versioning as one-off tasks. Expiring tokens and deprecated versions tend to cause incidents exactly when nobody is on call, so write both into the operations documentation from day one.

In what order should you read it?

There is no need to read it front to back. Start with API Paradigms and the security material, with two questions in mind: what kind of API is this, and how does authentication work and who grants access. Next come Scaling APIs and the chapter on managing change, where you look for answers on request limits, page sizes and the deprecation schedule for old versions.

Keep Appendix A open alongside. The book presents the worksheets as a template for the API design process; you can use the same template as the frame for a discovery checklist, simply switching the viewpoint from designer to questioner.

A closing exercise: pick an API you are about to integrate with and, following the way Appendix A turns the design process into a template, build a one-page sheet with four boxes: API style, security, load limits and versioning.

In the load-limits box, write the sync-time calculation as in the table above, retries included. Take the sheet to the first discovery meeting and mark which boxes the client cannot yet answer.

Leave the design best practices for later, when you need to propose changes to the API or build an adapter layer. The developer programs material is for when the client wants to open its API to partners, or when you move into a role closer to product.

Turning it into a line on your CV

The skill of reading other people’s APIs is hard to see if all you write is “API integration”. Be specific about which request limit or version upgrade you handled and what came of it, for example how long the sync job took after you recalculated the page size.

In interviews, the four questions on paradigm, security, load limits and versioning make a good frame for telling the story of a difficult integration: what you asked, what you found, what you decided.

Good developers read the client’s API documentation. Good FDEs read what the people who wrote it left out.