In-depth review of Irresistible APIs: Designing web APIs that developers will love

Introduction

This blog post is a starting point for a series of in-depth book reviews.

I read around 10-15 books a year, I know how much time it cost and how crucial it is to pick up the right one. If you are investing your own money in a book, it's even more important to get as much information as possible. You want to be sure that you are not buying a pig in the poke.

Before scheduling anything to read, I search for recommendations and reviews in the following places.

• Goodreads
• Publisher websites like O'Reilly, Manning, Packt.
• Book marketplaces like Amazon or Bol

Unfortunately, recommendations put there are of little value. What is the difference between 3 stars and 5 stars?

Reviews tend to be either too personal and opinionated, or too short and devoid of details. In my experience, the most trustful ones pop up from time to time on Goodreads and Amazon. Yet, it is still hard to draw a proper conclusion.

The nice thing is that some publishers give you an option to read one or two chapters for free. This is better, but it's still not enough to give you a good picture of the entire book.

Because of this, I came up with an idea to create in-depth reviews of technical books. If the topic interests me, which is in case of APIs, Domain Driven Design, Test/Behavioral Driven Development, Software Architecture, Object Orientation, Design Patterns or Web Development with PHP and Symfony, my mission is to read out all the possible books out there.

So the first book I've crunched and reviewed for you is Irresistible APIs: Designing web APIs that developers will love by Kirsten L. Hunter.

Book description

Book overview

Irresistible APIs provides information about planning, designing, and managing the development of web REST APIs, from business value through developer support.

This book's audience varies a lot. If you are a developer, technical lead, product manager, or even an executive, this book should be a good fit for you.

Kirsten divided her book into two parts. The first part, titled "Understanding web APIs", talks about technologies and best practices for API creation and infrastructure. It consists of four chapters and covers HTTP and REST basics as well as advocates for API First approach.

• Chapter 1. What makes an API irresistible?  (download free chapter)
• Chapter 2. Working with web APIs
• Chapter 3. API First (download free chapter)
• Chapter 4. Web services explained

The Second part, titled "Designing web APIs" talks about the overall strategy for API design and creation. It consists of five chapters and covers determining business value, creating metrics and understanding use cases, as well as how to document your APIs.

• Chapter 5. Guiding principles for API design
• Chapter 6. Defining the value for your API
• Chapter 7. Creating your schema model
• Chapter 8. Design-driven development
• Chapter 9. Empowering your developers

Code samples cover a simple Express application which resides in webapp directory. They use Docker image which runs on Ubuntu and requires NodeJS 4.0 environment. Besides that, schema_models directory gives examples of scheme modeling languages. Blueprint (Format 1A), RAML (0.8) and Swagger (2.0), also known as OpenAPI.

Chapter 1. What makes an API irresistible?

This chapter talks in simple words about various API concepts and briefly present what will happen in the following chapters. There are no technicalities here, so it should be an easy read for everyone.

In the beginning, it describes an irresistible API as straightforward to use, well documented and supported. Moreover, its use cases must be well communicated and demonstrated. Besides that, using it should be a joyful and engaging experience for developers.

This chapter in one sentence describes REST (Representational State Transfer) as a type of APIs that are resource based where the clients interact with the servers by requesting things rather than actions.

It briefly touches the topic of mashups, which are applications that combine many APIs together to create new user experiences.

Next, it emphasizes the developer experience as the most important factor of the successful API. REST is good if you try to encourage creativity and engagement with a larger community, or inspire developers to reimagine your main product via the APIs. SOAP is good if your API needs action-based methods that do a small number of things in a specific manner.

Then it tries to explain what Web APIs are and what the protocol means, mentioning HTTP as a well-known protocol used by web browsers. Suddenly it jumps to RESTful and gives some silly, coffee shop example.

After that, the author tries to answer a question "If you need an API" and why it's good to choose REST APIs with only one response format, JSON.

Next, a short subsection about Versioning begins, when releasing a new version of API every week or two is discouraged. Which version of your API is used is actually in the hands of developers (aka clients). The least breaking changes you introduce, the better.

Soon after, in the subsection on Marketing to developers, the author claims that "Developers don't tend to be inspired by pretty pictures or taglines - they want to play with toys.". They come to your API with simple questions like "What can I do?" and "How do I do X?", therefore give them example code and applications.

Then another section starts, about Common Pitfalls of Organic APIs. In here, the author states that APIs has been around us for over 10 years. Thus, we have the advantage to not make the same mistakes as companies like Netflix, Twitter, Flickr did. Pitfalls she mentions include: Lack of vision, not prioritizing the developer experience and bad API design.

After this, the author starts the topic of API Creation Process, where she presents briefly four steps that shall lead to a successful web API.

• Determining your business value
• Choosing your metrics
• Defining your use cases
• Designing your API and creating a schema model

Then, the author introduces three main schema modeling languages, including

• Blueprint from Apiary, which uses Markdown
• OpenAPI (previously Swagger), which supports JSON or YAML and features the ability to include abstractions of objects in the system (i.e: user, car)
• RAML from Mulesoft, which uses Markdown and also supports abstract objects.

Then, the author moves to the Industry standards and advocates for using API Commons, where organizations can upload their schema for re-use by other API producers.

In the end, the author encourages to have a developer portal full of documentation, example code, and engaging tutorials. If you additionally share your business value and metrics, it should be even better. She mentions Twitter and Twilio portals as places with amazing developer experience.

Chapter 2. Working with web APIs

This chapter is more technical so it may pose a little challenge for non-technical readers. Developers of any kind should grasp its contents with ease, however, if you have never worked with Nodejs, Javascript, jQuery, Bootstrap, I advise you to skip the installation steps.

To avoid the installation hell, there was once a demo page http://www.irresistibleapis.com/demo, but this is no longer the case...

As an alternative, if you are Developer, you may try to install it locally following section 2.6 Install your own API and Front End. Unfortunately, instructions there were outdated and didn't work for me on Mac with Docker. Also, her Docker Image on Docker Hub was pretty misleading and didn't work either.

I managed to set it up, by cloning her Github repository https://github.com/synedra/irresistible and adjusting Dockerfile as follows.

FROM ubuntu

ADD ./ /opt/api
WORKDIR /opt/api

RUN apt-get update -yq && apt-get upgrade -yq && apt-get install -yq curl git nano vim wget gnupg
RUN curl -sL https://deb.nodesource.com/setup_8.x | bash - && apt-get install -yq nodejs build-essential
RUN npm install npm -g
RUN npm install express -g

RUN cd /opt/api/webapp && npm install
RUN cd /opt/api/swagger_mock && npm install

CMD ["/usr/bin/node", "webapp/server.js"]

Then I had to build the image locally, with

docker build . --tag tekmi:irresistible

And then run the container with properly exposed ports.

docker run -d -p 8000:8080 tekmi:irresistible

After all that, I could finally explore the API http://localhost:8000/api/v1.0/toppings and see the helper client application under http://localhost:8000/demo/

The first section covers HTTP basics in a very approachable way and is full of helpful infographics. The author demystifies HTTP Request, HTTP Response, and talks about mapping CRUD actions into HTTP Methods

• Create → POST
• Read → GET
• Update → PUT
• Delete → DELETE

In another two sections, the author describes her Toppings API. She presents a diagram with the complete set of interactions and a table with possible API calls.

Next section enumerates multiple ways how you can interact with APIs, including

• Browser (i.e. Chrome with Developer Tools)
• Command line (i.e. curl)
• HTTP sniffers (i.e. HTTPScoop which no longer exists, Fiddler, Charles Proxy, Wireshark)

This is a pretty lengthy section, which shows in detail how to use Chrome, Curl, and HTTPScoop so it may be boring if you know those tools.

Chapter 3. API First

This chapter reads like a novel and a bit like spaghetti, presenting easy-to-read material without many technical details.

The author advocates for using API First model, which places your API at the center of development. Front-end websites and Mobile integrations should always talk to your API first and not directly to Back-end systems.

Such an API will become a crucial part of your company's strategy (Functional equality) and not an "extra, nice to have" side product. Moreover, it should get enough attention and support from stakeholders and managers. Your developers will be happier too since they will write the business logic once (Code consistency and Increased productivity)

Somewhere between the lines, the author gives a laconic example of highly scaled systems (i.e. stock trading systems), that may not benefit from API First, since it may hinder the performance.

Last, lengthy section presents some case studies on how companies have moved to API First model, including Twilio, Instagram, Etsy, 3scale, Akamai. If you are a product owner or technical lead, this may be a good read for you.

Chapter 4. Web services explained

This chapter is the most technical so far, so it should be enjoyable for junior or medior developers.

In the beginning, the author covers HTTP fundamentals, claiming that HTTP is the most common transaction protocol for REST APIs, thus almost all REST APIs use it. She presents in greater details following concepts

• Addressability - Every HTTP request must have an identifier; this address is called a uniform resource indicator (URI) in this case.
• Status codes - As every request must have an address, every response comes back from the server with a status code indicating the success or failure of the action requested. Status code groups (5xx, 4xx, 3xx, 2xx). HTTP 4xx status codes, including 400, 401, 403, 404 and 405
• Body - When content is associated with a request or response, this data is sent as the body of the request or response. For requests, this is generally the case for create and update options (POST and PUT).
• HTTP verbs - With POST, GET, PUT, and DELETE, HTTP has verbs available to cover each piece of a full client-server transaction.
• Headers - HTTP contains headers, additional elements providing additional context for a request, and parameters, separate options for the request. Common items passed in a request via headers include language preference, response format preference, authorization information, and compression preference. Request headers: Accept, Accept-Language, User-Agent, Content-Length, Content-Type Response headers: Content-Type, Access-Control-Allow-Headers, Access-Control-Allow-Methods, Access-Control-Allow-Origin
• Parameters - Parameters are frequently used in HTTP requests to filter responses or give additional information about the request. They’re used most frequently with GET (read) operations to specify exactly what’s wanted from the server. Parameters are added to the address. They’re separated from the address with a question mark, and each key-value pair is separated by an equals sign; pairs are separated from each other using the ampersand.

Next section tries to explain REST Web Services, but does a poor job and is very laconic.

The author claims that REST-style APIs are effective when designed and built around HTTP. The HTTP verbs match exactly to the create, read, update, and delete (CRUD) actions needed. The existing error framework is more than sufficient for a strong framework.

Then she tries to give some best practices, such as

• URI (web address) for a resource must be unique for each item. This is the item’s unique identifier and is used for any action on that item
• POST is generally used to create operations in REST by operating directly on a list resource rather than a single object
• Your resources should be nouns, not verbs (so /orders/ instead of /create_order)
• You should conform to the HTTP status and error codes and work hard to achieve and maintain consistency
• For mobile devices, you should provide a single call per page so that applications can be performant and successful (this may be out of line with the idea of REST, but you should be flexible rather than standard dogmatic)
• Idempotency, the idea that when sending a GET, DELETE, or PUT to the system, the effect should be the same whether the command is sent one or many times.
• Don't use GET (read) verb to delete items in the database.

Chapter 5. Guiding principles for API design

This chapter is the first chapter from the Part II. It's easy to read, thus all non-developers should be delighted. Over the next chapters, there will be less and less technical stuff so some developers may become seriously bored.

The author divided this chapter into five sections, discusses the following guiding principles of API creation

• Don't surprise your users
• Focus on use cases
• Copy successful APIs
• REST is not always best
• Focus on the developer experience, not the architecture (communication and consistency are critical while documentation should tell a story)

Chapter 6. Defining the value for your API

This chapter, lacking technical details, is a perfect material for non-developers. It encourages to follow the following steps during the process of designing an API

• Determine business value
• Define metrics
• Create use cases

In the first section, the author focuses on most common business values, such as

• Monetization - When the API is the main or only product for the company, this is an obvious necessity. (e.g: Twilio)
• Usage - If you have a product with an activity stream or any type of social-based application, the goal of the API is to drive usage. You want to know how many times the end user interacts with your system and you want to encourage them to do so. (e.g: Twitter, LinkedIn, Facebook)
• Partner retention - When your company wants to retain and engage its partners, your API should focus on usability targeted at the use cases your partner may want. This could include automation within your system or integration of your reporting with their own dashboards. (e.g: FedEx)
• Market dominance - In this case, your API should be focused and agile in order to become the leader in the industry. (e.g: Netflix)

In the next two section, the author discusses Metrics and Use Cases, which both depend on the Business value you have determined for your API.

Chapter 7. Creating your schema model

This chapter is a bit technical, but it should still be a valuable piece of information for product managers and executives.

It presents and discusses in greater detail two most common schema modeling tools (i.e. RAML and OpenAPI), encouraging to use them before even the development of your API has started.

In the first section, the author talks about Schema Model as a contract describing what the API is, how it works, and what the endpoints are going to be. With a schema model, you can ensure that everyone has a shared understanding of what the API will do and how each resource will be represented when the API is complete. Each of the schema modeling languages has tools available to automate testing or code creation based on the schema model you’ve created.

Next section focuses deeply on RAML, RESTful API Modeling Language supported by Mulesoft. The author created an example RAML 0.8 model so that you can try it out on Mulesoft's Anypoint portal if you are signed up there.

The next section focuses on OpenAPI (previously Swagger), supported by SmartBear. The author created an example Swagger 2.0 model, which you can open in Swagger Online Editor. No registration required, but keep in mind that at the time of writing, the latest version of OpenAPI is 3.0.

This chapter does not mention anything about Blueprint, but you find an author's example of Blueprint 1A mode under her Github repository.

Chapter 8. Design-driven development

This chapter should be an easy read for everyone, except a tiny technical bit about Git and Heroku.

In the first section, the author enumerates development strategies for your API, including

• Waterfall development
• Agile/test-first development with methods as Scrum and Kanban.
• Behavior-driven development which extends test-driven development.
• Design-driven development which adds a design layer on top of TDD and BDD.
• Code-first development, where API becomes a subproduct of main product and is not considered as a first-class citizen for your organization.

Next section focuses on Project management for APIs, where the author advocates for design-driven strategy. She suggests starting in parallel with functional specification and schema model. Once both of them are completed, acceptance criteria and unit tests should be developed. After all of this infrastructure is in place, the development iterations can begin.

She encourages to create functional specification document, which should answer at least the following questions

• What problem is the project solving?
• What is the business value?
• What are the metrics and use cases?
• What resources are needed or available?
• What does "done" look like?
• What could go wrong?

Next section talks about Road-testing your API, where the author proposes to create the Mock server using the schema model in order to help you validate your plan with customers.

She already provided a Nodejs code sample for Mock server based on Swagger schema and now she suggests using Heroku PaaS to deploy it.

If you don't want to hear about Heroku, I have an alternative for you. If you used my Dockerfile before, you can create another container and run her Mock server locally as shown below.

docker run -d -p 8001:8080 -w '/opt/api/swagger_mock' tekmi:irresistible node index.js

Then you can examine JSON version of Swagger schema model under http://localhost:8001/api-docs and explore Swagger console here http://localhost:8001/docs/#!/Default/toppingsGet

Note that you won't be able to Try out any calls since the Swagger schema model is still pointing to author's domain irresistibleapis.com:8080 which is not working...

In the next section, the author focuses on acceptance tests and use cases.

She proposes to use a typical User Story and then turn it into a testing scenario. The difference between the user story and the testing scenario is that the latter will describe specific actions and their outcomes, to solidify exactly what’s needed to validate that the code covers the user story. Some user stories might end up with multiple scenarios, but each user story should have at least a single scenario.

From here, you can create an acceptance test case. The acceptance test case is different from the Unit test case because it tests the behavior and workflow of the user cases, rather than the exact behavior of specific functions within your code.

The goal of the acceptance tests is to follow the workflow that developers will use to interact with your system. When you have these acceptance tests, you can use them as the basis of your documentation tutorials.

In the last two sections, the author talks a bit about Development planning and Sprints, giving a quick introduction to Standups, Kanban "Swim Lanes" and Retrospective.

Chapter 9. Empowering your developers

This is the last chapter of the book and it fairly simple read for everyone. The author talks about the importance of providing the developer support once the API has been released into the wild.

The first section discusses the four pillars of API support, which should improve your client developers' understanding, engagement, and integrations with your platform.

• Communication (Overall Vision, Business Values, Metrics)
• Documentation (Reference Documentation, Workflows, Tutorials)
• Building Blocks (Sample Code, Reference Applications, Tools and Techniques)
• Support (Service Level Agreement, Forums)

In the following section about Communication, the author shows the failures of communication made by Netflix, LinkedIn, and Twitter and praises the strong communication of Google.

Next section is about Documentation, focusing on Reference documentation (Endpoint documentation, System guides, Complete Requests/Responses), Workflows (Guide for each Endpoint, Simple tasks) and Tutorials (Based on Use Cases, Clear and complete steps, Tie tutorials together)

She shares a handful of guidelines about writing Tutorials and gives a detailed example of Getting Started tutorial with a bit of Python code. Sadly, her website http://toppings.com/code_samples doesn't work again...

Next section is all about Building blocks, so the author suggests providing to your client developer's the following code samples

• Authentication libraries, since they often require knowledge of both encryption and HTTP protocol.
• Working examples for the endpoints, workflows and integration possibilities
• Sample applications which are more functional.

Besides that, she talks about Apigee console, which was actually sunsetted in March 2018 and Twitter Rest Console, which is not accessible anymore...

Then she mentions curl, HTTPie as command-line utitlies and enumerates HTTP Sniffers (HTTPScoop, Charles, Fiddler) again.

In the last section, the author focuses on Developer support, claiming it's best to try to get back to developers with questions within a business day. Additionally, she advises organizing your developer portal well so that the information is easy to find and access.

At the very least, she encourages to provide an interactive support (i.e. forum, help desk, email alias) as well as non-interactive one (articles, an explanation for recurring questions).