Book Review: The Design of Web APIs

Arnaud Lauret’s The Design Of Web APIs is a comprehensive, thorough guidebook, teaching you everything you need to know about web APIs and API design in general. No matter who you are or how far along you are in your development career, you’re likely to learn something new from Lauret. Or, at the very least, get a solid refresher course on the best practices of API design.

In this article, we review of Arnaud Lauret’s The Design of Web APIs from Manning Publications.

APIs are becoming big business. As noted by the consultancy company Deloitte in 2015 Tech Trends, “Application programming interfaces (APIs) have been elevated from a development technique to a business model driver and boardroom consideration.” Businesses are seeking ways to leverage and monetize all of their assets in all manner of new and interesting ways.

The API development firm Smartbear report that 75% of businesses plan on creating an API for either internal or public-facing use. With so much attention being paid to APIs in recent years, business owners are likely becoming curious about what an application programming interface is how they might develop one.

As Arnaud Lauret puts it, “Whether they’re seen as simple technical interfaces or products in their own right, whole systems, whatever their size and purpose, rely on them. So do entire companies and organizations, from tech startups and internet
giants to non-tech small and medium-sized enterprises, big corporations, and government entities.”

That’s where Arnaud Lauret’s The Design Of Web APIs comes in. Manning Publications and Arnaud Lauret have teamed up to teach programmers and developers, everything they need to know to create a fully-functioning web API from the ground up, no matter their level of expertise.

The Design Of Web APIs by Arnaud Lauret (Manning Publications)

APIs aren’t exactly plug-and-play, out-of-the-box tech solutions. They’re tools, meant to fulfill a function. That means creating an API of any kind requires thinking like a programmer/developer, rather than simply being another software solution you buy to fulfill some need.

The Design of Web APIs by Arnaud Laurent is a thorough, comprehensive guide to developing web APIs, from the ground up. It’s equal parts textbook, workbook, and theoretical discussion all in one. It’s designed for developers at any skill level. More experienced developers may find some information to be redundant but just skip ahead if that proves to be the case. There’s more than enough advanced knowledge in the book to make it worth your while, even if you’re already a seasoned API designer/developer. Even better still, read through it all and brush up your API design knowledge! We can all stand to hone and polish our skills from time to time.

Introducing APIs

The first four chapters of The Design of Web APIs serve as a basic primer on APIs, in general, and web APIs specifically, getting you ready to begin creating your own programming interfaces. It lays out the terminology you’ll need to follow the later parts of the book. It also details some of the thought patterns that go into designing a good API, which are developed further a little later on in the book.

The first couple of chapters are useful for those just getting started with API development and design, all the more so due to the presence of a number of useful illustrations and metaphors. He starts off by defining what an API is and does. He defines an Application Programming Interface as “a point where two systems, subjects, organizations, etc. meet and interact.”

He then goes on to define some of these common concepts using concrete, practical, easy-to-visualize examples. For instance, Laurent uses a flowchart describing the way a restaurant operates as a way to illustrate how an API calls and receives information.

Getting Acquainted With Web APIs

The Design of Web APIs follows this format throughout the book. The beginning of each chapter introduces the concept and the following subsections break it down into smaller topics and drill down into each one. It’s a format that most tech-savvy readers will be familiar with, guiding you from a complete novice to having a relatively thorough understanding of the concept by the end of the chapter. This is further emphasized by the inclusion of introductions, sidebars, and summaries, for each subsection as well as the chapters themselves. This helps make the knowledge you’re ingesting more concrete.

Consider this overview of Chapter 5: Designing A Straightforward API, as an example.

This Chapter Covers

  • Craft straightforward concepts representations
  • Identify relevant error and success feedback
  • Design efficient usage flows

The Design of Web APIs itself follows a similar trajectory. It takes you from being a complete novice to close to an expert by the time you’re finished reading its comprehensive, thorough 322 pages.

This format works wonderfully for beginner web API designers, who stand to benefit the most from this book. Lauret is adept at illustrating API development and design principles using real-world examples throughout the book. He uses the example of a busy restaurant to illustrate how API calls work, for example. He also uses a series of humorous metaphors to point out examples of bad design, like calling an object a Kitchen Radar 3000 instead of simply a ‘microwave.’

Let me introduce, with a deep and loud voice, the Kitchen Radar 3000 (shown in 2.1). According to the advertisement, this kitchen appliance brings state-of-the-art military-grade components into your kitchen so you will never ruin any recipe and will become the fastest cook in town. Whoa, totally thrilling, isn’t it?

These examples help to keep the text lighthearted and flowing nicely, which makes The Design of Web APIs eminently readable as well as useful. It’s designed for readers as much as developers, which will be a blessing for lay-people looking to get into web API design.

As far as advanced developers and programmers are concerned, the latter chapters are going to be more useful. The Design of Web APIs is worth reading for the chapters on designing organized, concise, and secure APIs, which are some of the most pertinent issues facing API designers today. The other most pertinent piece of advice is ‘avoiding the provider’s perspective,’ which is mentioned throughout the book. As Lauret puts it, “Designing APIs without principles, totally out of context, and
without taking into consideration both side of the interface — the consumer side but also the provider’s one — is the best way to ensure a total failure.”

That means thinking like an API consumer rather than a programmer when you’re designing your programming interface. It’s a small but subtle difference that can have major repercussions on your programming.

While the knowledge may be a bit primary for people already working with APIs, it’s still a good refresher. It’s also laid out in such a way to further and deepen your understanding. It’ll benefit your coding, no matter where you are in your API development career.

The Design of Web APIs lives up to its name. It focuses on design, coming across as more of a philosophical introduction than a textbook or course. It’ll teach you to think like a designer/developer, which is actually a benefit. APIs are rarely a plug-and-play solution, as we noted at the beginning of this review. You’ll need to think critically and outside-of-the-box, almost by nature, as you’re the one creating the tools. This book will teach you to program efficiently, which is worth more than its weight in bitcoin if you’ve ever tried to code an API from scratch without pre-meditation.

The only thing that I, for one, would’ve liked to have seen in The Design of Web APIs would be some sort of test questions or practice problems at the end of the chapters. While it’s mostly a philosophical introduction, having a chance to implement some of these principles yourself would help them to be more concrete and understandable. There are no shortage of API design lessons, courses, and tutorials out there. You could easily source some external learning material to practice some of the concepts introduced in this book.

Is The Design of Web APIs Worth it?

With any tech-related book, it always raises the question, “Is it worth spending money on, with so much free information and resources out there?” While it’s true, there’s an endless ocean of tutorials; blog posts; GitHub examples; online communities and forums, and so on, it’s hard to tell where that information is coming from. There’s also no over-stating the potential of a clean, clear, well-organized text. While you could no doubt design a comprehensive course on web API design on your own, if you were of a mind to do so, having it all laid out in one place in a thoughtful and masterful way is beyond useful. You’ll also learn some things you didn’t even know you needed to know.

If you’re serious about learning or mastering web API design, Arnaud Lauret’s The Design of Web APIs should join your programming library. Check back and consult it often to keep your skills honed and sharp to stay in the habit of thinking like a developer.