More and more businesses are creating web APIs. This is because APIs can add business value to a company as it offers developers an opportunity to interact with open platforms of others, for example by embedding external sources as social media on a website. The geospatial industry is has also embraced APIs: some companies are built around APIs (Mapbox, Carto), while others are now adopting an new approach to APIs, such as Esri who recently released a ‘pythonic’ API that allows for interaction with ArcGIS Portal and ArcGIS Online. Lately, there has been an increase in mapping APIs, as a result of Google ending its support a component of their mapping API called Google Maps Engine.

The growth of web APIs is self-reinforcing: as more web APIs become available, more people realize the potential of having their own API, which leads to more APIs being created. But not all APIs are instant successes, and even successful APIs may one day be deprecated, as the example of Google Maps has shown. The question is, then: what makes a good web API?

API evangelist

A recommendable source that answers this question is Kirsten Hunter´s book “Irresistible APIs: Designing web APIs that developers will love” from Manning Press, published recently. After having been involved in the API design process and implementation of large companies such as Netflix and Twitter, the author realized that these use cases might inspire others in designing web APIs.

The book is divided in two parts: the first part is called “Understanding APIs” and covers technologies and best practices for API creation and design, while the second part features an overall strategy for API design and creation. She starts off with a discussion on the overall goals and ideals for an excellent API program and offers a high-level description of technologies and techniques used for web APIs, as well as best practices for excellent APIs. Readers are encouraged to actively interact with a simple web API that allows to add and create pizza toppings on a virtual pizza, monitor HTTP browser traffic using HTTP sniffers and make API calls through a software program named curl.

API design principles

The second part of the book, titled “Designing web APIs” is the center part of the book. Important API design guiding principles such as “don´t surprise your users”, “focus on use cases” and “focus on the developer experience, not the architecture” are exemplified with real-world examples. The value of an API and how you measure this, combined with creating meaningful use cases is another important part of the API design process. For company´s whose only products are APIs, monetization is an essential business goal but in other cases, such as where an API is not a main product, there may be other business goals such as usage or partner retention.

Once you know why you need an API and what it needs to do, you can start modeling the schema of an API. The basics of schema modeling are explained through the two most popular schema modeling systems, RESTFul API Modeling Language (RAML) and OpenAPI format (previously named Swagger). API Development and project management strategies are covered in a chapter on design-driven development and help you building your API. A final chapter on providing a developer experience that makes your API stand out. This is a crucial part in API design and the success of your API depends on it.

Verdict

This book is best characterized by a quote on the back cover, stating that “a future is emerging where our APIs are our public face as much as our website, office space or sales staff. This book points the way”. What the author of this book has noticed correctly , is a change in software architecture design over time where an API is not just an add-on, but an important part of that same architecture that serves to extend a company´s main product and can generate more revenue or users. This change also requires a more integrated design approach when designing and building an API. The advantage of successful use cases allow others to build on, as well as open APIs from company such as Facebook. The design principles and use cases are the main attraction of this book and the reason why I´d recommend it.

The book is very accessible, judging from the non-technical language and examples. This makes it suitable for a wide audience, but the downside of this approach is that software developers hoping to find a technical book on API development will probably be disappointed with this book. This is because it is not a tech book per se, but one that offers a high-level overview of how you design APIs before you build them and all organizational challenges that come with API design. There is little technical content  – it’s not worth reading the book for technical content alone.

Unfortunately, the first part of the book is not as good as the second part. The reason for this is that the book lacks unambiguous definitions for key concepts as ‘APIs’, ‘web APIs’ and ‘REST APIs’. The author explains the term web API but uses different interpretations in different contexts, which is not helpful in understanding the concept of web APIs. I would have preferred a more in-depth and technical approach during the first part of the book. Here, the author seemed to be in a hurry in order to quickly serve the main dish, which is the part that covers API design. Even though this is not a perfect book, it´s recommend for the chapters API design and use cases.