The Design of Web APIs

by Arnaud Lauret

The Design of Web APIs is a practical, example-packed guide to crafting extraordinary web APIs. Author Arnaud Lauret demonstrates fantastic design principles and techniques you can apply to both public and private web APIs.

Genres: Programming, Technology, Computer Science, Technical, Web, Software, Design

392 pages, Paperback

Published October 1, 2019

Reviews

[Mustapha Hadid · Rating 5 out of 5]

This is a comprehensive, well-structured book covering almost every aspect of restful web APIs with occasional brief comparisons to well-known alternatives ‒ GraphQL and gRPC. Although the book explains the concepts in a way that suits those with little or no prior experience/knowledge, there's a lot of knowledge and wisdom there even for experienced API developers. The book uses OpenAPI specifications, with decent illustrations, to communicate the examples, the real-world examples.

The book is divided into three parts. The first part introduces the fundamentals of web API design; you may skip it if you're familiar with web API principles. The second part is where you learn how to design easy to understand API and the process of decomposing the requirements into web interfaces; I highly recommend this part regardless of your experience level. The third part, the most valuable part for me, explains the contextual elements you need to consider to design a decent API ‒ things like breaking changes and extensibility, network communication concerns (compression, caching, and conditional requests), and choosing the best API style based on the context.

[Bartłomiej Falkowski · Rating 2 out of 5]

I'm disappointed. I expected much more content and technocratic knowledge. I understand the idea of delivering technologically agnostic book but it's challenging task to do it and still deliver value.

What I liked:
- It's a good start for someone who wants to build a public api and has never done it before

What I didn't like:
- It's actually valuable position only for people who want to build public api.
- In the end it's an just extended description of REST principles ant restful api (+ OpenApi)
- I understand the power of metaphore. However, I felt a bit confused after another comparing software api to hardware devices apis (microwave, cooker, remote and so on). I was like "I got it, why are you still trying to convince me?". Metaphore is good but metaphore overdose is just annoying :)

[Pranav Singh · Rating 5 out of 5]

Great book for developers who work on planning, creating & modifying Open APIs or API that are exposed to other Third parties.

Started with basics, it grows to all the way down to nitty-gritty of API management. Good Read Indeed

[Adam · Rating 4 out of 5]

As an API developer, it was very insightful to understand that there are other perspective which have to be taken into consideration, beside a provider's.
Examples of how to design inputs, responses, how to start with set of goals and transform it into functional API are extenstive and well-put - after initial read, it's worth coming back to schemas and tables of suggestions as a reference to how to design API or extend existing one.
Main con of this book are written examples - IMO they are too lengthy, could be more concise.

[Jevgenij · Rating 3 out of 5]

At the first glance this seems to be a very comprehensive book, covering all aspects of API design. On closer inspection it has many problems:
- Covers a lot of very very basic stuff, author writes for those who see a computer for the second time in their lives.
- Very wordy, simple things are explained in many many words.
- Idealistic in how the design is presented, it would take ages to design an API doing everything by the book, and no possible trade offs or practical considerations are presented in the book.

[Eric Horesnyi · Rating 5 out of 5]

I have helped 100s organizations build APIs for 5 years, and could find in this book not only principles but also a methodology to design APIs, holistic, obsessed with API user experience but also security and domains. This is now the methodology I recommend for people to use whenever they consider their API as a product that need to bring value and differentiate.

[Alex · Rating 5 out of 5]

An amazing and deep book which will teach you how to design, test, make secure and document RESTful APIs.

[Michael · Rating 3 out of 5]

3.5* = It was a decent book, but I likely wouldn't read it again unless someone did some serious convincing.

The book gets so close to being really good, but unfortunately it just wasn't technical enough for my personal preference. It is very much written to be read by someone of low to moderate technical knowledge.

I'm a software engineer, so I naturally wanted a more technical guide. For instance, there was only one small section on auto-generated specifications, which only listed the cons of using such a process (there was another mention in the final chapter but wasn't given its own section). I would have enjoyed an explanation of why you might use a generation library, what an example usage might be, and compare that to the manual process.

The best thing the book did was to give me an overview of what needs to be done, and an awareness that API guidelines exist and should be considered before reinventing the wheel.

Another complaint I have is that the book is full of huge diagrams with paragraphs of filler. The author creates these often complicated diagrams that are self-descriptive and can be fully understood without much supporting text, then proceeds to describe each part of the diagram in excruciating detail. Or throws in redundant diagrams that add nothing to my comprehension or paragraphs that seem to repeat early points. It felt very much like filler to make sure the book met some quota on length.

[Serhat M. · Rating 5 out of 5]

The book provides a broad view of the decision-making process of API design with rich visualizations and comprehensive content in a beginner-friendly tone. However, it can also be useful for seasoned developers. The book covers a wide range of topics, starting from HTTP and REST API basics, to more complex topics such as decision making between REST, gRPC, and GraphQL. Inexperienced engineers can benefit from the book to strengthen their fundamental knowledge, and experienced engineers who are often expected to prepare guidelines, define standards and pick best practices for various topics, such as APIs, can benefit from the book as a reference resource.

Overall, I enjoyed it!

[Marcin · Rating 3 out of 5]

This book describes many aspects of REST API with some comparison to GraphQL and gRPC (but very little - a few paragraphs). In the book, you don't find any code. Only OpenAPI schemas. I expected more technical patterns, but I received a theory on how to build a good REST API. There is a chapter about security, but no info about storing JWT Refresh Token in cookie.

I think this is a good book for someone who has never created REST API to see which problems can occur, how to resolve them, and what means good API.

[Beggie S · Rating 5 out of 5]

Great book for REST API designers - from novice to expert. I really liked the clean structure and the way the topics evolve: from REST API basics through security, evolution, lifecycle and efficiency.
As a probable flaw, I’d say I expected to find a deeper comparison of the value of webhooks vs sse vs grpc in real-life scenarios.

Still, the book provides a great frame of reference for the relevant building blocks of API management.

[Alex · Rating 5 out of 5]

I found this to be a very helpful reference for what it was. It doesn't delve too deeply into technical specifics outside of the OpenAPI specification, but I think this is to its advantage. There are plenty of resources online for working through an API implementation in whatever framework; this book instead focuses most of its time on broader design goals and why you might choose a given framework for a particular task.

[Ioannis Papikas · Rating 5 out of 5]

This is an excellent book to start designing your first RESTful API. It includes a clear walkthrough from the initial goal setting methodology and gradually diving deep into RESTful API, resources, documentation, extensibility, readability, security and finally performance.

The book is full of schematic representations and examples to help the reader understand each theory in practice using real case scenarios, although sometimes the scenarios are a bit more complicated from the banking world.

[Roman Mkrtchian · Rating 4 out of 5]

There is a good educational effort in this book. Most of the concepts are explained with comparisons to examples from everyday life, and everything is explained twice through drawings and text.

But because of that the book does not always go very deep in some of the topics (like security, or non-REST APIs) compared to what it could have, given its size.

Overall it remains a good book that gives guidelines to write web APIs from someone who has experience in doing that.

[Erlend · Rating 4 out of 5]

This is a really thorough book on designing Web APIs. It has all the information most people would want, but its examples and motivation sections can be a bit too long at times.

[Alexander · Rating 3 out of 5]

I was a bit tired by the author’s obsession with diagrams with excessive details. Otherwise, quite a good content.

[Chiranjivee Thakur]

Awesome book to learn API design.

[Valentino Gagliardi · Rating 4 out of 5]

A bit lengthy and verbose. You won't find any code in this book, but this text is a must-read for REST API designers and implementers, full of practical advices and lesser known tricks.

[Adam · Rating 2 out of 5]

Way too verbose. Not sure what's the target audience is, but the book is extremely basic even for non-technical folks like myself. States the obvious on the loop - 350 pages of suffering.

[José Córdova · Rating 5 out of 5]

Wonderfull

[Viktor Lototskyi · Rating 4 out of 5]

Good up-to-date book for beginners/intermediate level (as it states it is).
Not a lot of advanced stuff if you already built several APIs and looking for in-depth topics.

[Yura Zdyrko · Rating 5 out of 5]

Great book. Makes me appreciate APIs much more.

[Xathras · Rating 4 out of 5]

It's a decent book if you're a RESTful API beginner, but overlong and wordy if you have some experience. I enjoyed the book, I just wish the author favoured brevity a little more.

[Jake Schmitz · Rating 4 out of 5]

Provides a goods structure to think about and document an API. Good stuff cover to cover!

[Bas Langenberg · Rating 4 out of 5]

Great read explaining how you should design api contracts.

[Javier · Rating 3 out of 5]

It will help anyone looking for knowledge about how to design and build an API though it took me longer to read because I felt something it was heavy to read, like it could have been shorter

[Alb85]

Noioso. L'ho sfogliato velocemente. Forse è il topic che non mi incuriosisce abbastanza.

[Jiří Mareš · Rating 4 out of 5]

Great book, the design using openAPI is great described into the smallest details.
But some latter chapters are too obvious so a little bit boring.
I am looking forward to second edition.

[Tim Verstraete · Rating 4 out of 5]

Really liked this one, it gave me a very good idea on how to tackle REST API's and how to start designing them. I will definitely use this for my work ...

[Matt · Rating 5 out of 5]

Great way to describe how to design APIs. Builds from the purpose of the API, its key concepts, and from there into the detailed considerations impacting API design. The specification examples included are useful and downloadable via the publisher's page for the book.

Wish I had a copy of this when I started my current project!