Irresistible APIs

Kirsten Hunter

• Publisher: Manning Publications
• Year: 2016
• ISBN:
  9781617292552
• Topic: Design
• Subtopic: Web Design

Irresistible APIs provides step-by-step guidance for designing APIs that reflect an application's core business value, delight the developers who use them, and will stand the test of time. In it, business product managers and developers learn how to treat an API as a first-class product.

Part 1. Understanding web APIs

This part covers the basic technologies involved in web APIs to help readers understand the context of this type of platform. Starting with a discussion of what makes an API irresistible, the chapters in part 1 drill down into the user experience for APIs, the ideal API infrastructure (API First), and an explanation of the technologies used for web APIs.

Chapter 1. What makes an API irresistible?

This chapter covers

• Defining a web API and what it can do
• Ensuring a great developer experience
• Avoiding common pitfalls

An API is an interface into a computer system—an application programming interface. Historically APIs started out as highly coupled interfaces between computer systems. Web APIs, which are much freer and less tied together, have been evolving for quite some time, but recently developers have seen a huge explosion in the web APIs available to them. Many of these APIs were developed without the end user (in this case, a developer using the API) in mind, resulting in a frustrating developer experience and a less successful web API.

An irresistible API is straightforward to use, well documented, and well supported, and the supported use cases are communicated and demonstrated well. Using your API should be a joyful and engaging experience, not a slog through a frustrating and never-ending series of challenges.

This book will help you understand how to create web APIs that are loved by developers, that are engaging and purposeful, and that will experience success. It also discusses the factors you should consider to determine whether you should have a platform at all. The guidelines included in this book are meaningful for any kind of web API, no matter the technology or audience.

When you’ve finished reading the book, you’ll have a strong understanding of the process needed to create excellent web APIs—APIs that enchant customer engineers and extend the platform’s reach naturally as those developers share their experiences with their colleagues. Although many different types of APIs are in use in the industry, each with its own advantages, this book focuses on the development of RESTful web APIs. Web APIs decouple the functionality of the server from the client’s logic and features, encouraging client developers to use the data in whatever way works best for their application. Non-web APIs that tie the server and the client together tightly work to implement specific integrations between the client and the server. For instance, SQL, an interface language tied into many databases, represents an API, but the interaction is focused on specific actions. Exposing the data in a more free-form way wouldn’t work for many of the uses people have for databases or other closely coupled systems.

In addition, you’ll develop a good basic understanding of the technologies involved in creating a RESTful API. REST stands for Representational State Transfer and refers to APIs that are resource based—where the clients interact with the servers by requesting things rather than actions. The creation of web APIs is technologically simple: a skilled developer can use Flask, Django, Ruby on Rails, or Node.js to put together a basic REST API in a few minutes. Without a clear plan, design, and goal, that API is unlikely to be excellent, usable, or successful. How you use those technologies makes all the difference between a successful, irresistible API and one that lies fallow in the ecosystem with no users. The book is made for you, whether you’re a product manager, technical lead, engineering manager, API developer, or even a developer who wants to assess APIs you’ve created or ones you’re looking to use.

This chapter is focused on helping you understand the overall ecosystem of web APIs—what the terms mean, what things you want to accomplish (and avoid!) in creating your own API, and how to decide whether you need an API.

1.1. Integrating social APIs into web content

You likely use products that are incorporating APIs all the time. The share button you see on news sites and blogs uses the APIs for those social sites, like Twitter, Facebook, or LinkedIn. If you can “Sign in with Twitter,” the site you’re visiting is using Twitter’s API to identify you. This makes for a much better user experience, because you don’t need to remember more usernames and passwords and you can jump right into enjoying the system. Figure 1.1 demonstrates a website displaying several share buttons, enabling the reader to add the page to their feed in the social network. Figure 1.2 shows how an API can propagate changes to the clients so they can update their application’s guidelines.

Figure 1.1. A blog incorporating a Twitter feed as well as API functionality for sharing to multiple social networks. A widget provides buttons for each of the social networks—Google+, Twitter, LinkedIn, and Facebook—and this widget incorporates that network’s API into the site in a manner that’s easy to implement.

Figure 1.2. Example API interactions with a monitoring application. When the monitoring application detects a change, it can propagate it to a website, mobile application, SMS notification, or email.

A RESTful API is a platform that exposes data as resources on which to operate. For instance, a contact records management application might make it possible for you to interact with users, contacts, and locations. Each of these would be exposed as a resource, or object, you can interact with, whether reading or writing changes. When you create a well-designed RESTful API, developer users can create applications commonly referred to as mashups. A mashup combines multiple APIs together to create a new user experience (see figure 1.3).

Figure 1.3. This chart describes an adaptations mashup using Freebase, Amazon, and Netflix. The user is presented with a grid of book-based movies matching a specific genre, and for each of the movies, the user is given the opportunity to watch the movie on Netflix or purchase the book on Amazon. This is an example of a mashup combining multiple APIs to create an integrated experience for the user.

As you can see, in figure 1.3 I created a mashup using Freebase (think of this as a database of the world’s information), Amazon, and Netflix. The mashup allows users to find books that have been made into movies and then buy the book at Amazon or add it to their Netflix queue. I used information from Freebase to add genre information for the movies so users can browse around and find the movies that interest them most. This is a simple example of mashing up three different APIs to create a new way for users to explore a data space. Frequently, websites or applications are also leveraging the APIs of social networks for logins, sharing, and showing your user feed.

This is a great place to emphasize one of the main concepts of this book. The developer experience for your customers is the most important factor in the success of your API. If you’re trying to encourage creativity and engagement with a larger community, or inspire developers to help you reimagine your main product via the APIs, REST might be your best bet. On the other hand, if your API needs action-based methods that do a small number of things in a specific manner, you may well want to make a non-REST API, using SOAP (Simple Object Access Protocol) or another technology designed for more tightly coupled clients and servers. Either way, the most important things to take into account are what your customers want and how you want them to use your API. Remember, developers are people too.

1.2. What is a web API?

The term API has been used for most of the history of computing to refer to the interfaces between computer systems, or between different programs on an existing system. Frequently these systems were peers, where neither of the systems was specifically a server or a client. For instance, a mail server might have used a database to store information, but the systems were inherently designed together, tightly coupled to work together seamlessly. More recently the term has been expanded to include web APIs, systems where a client—which could be anything from a web browser to a mobile application—contacts a web server and operates on the data on that server. The main difference here is that the developers who are writing the clients aren’t the same as the developers writing the interface—the system is truly decoupled.

To understand the idea of a web API, it’s useful to understand the protocol—the way the systems talk to each other. Think about the switchboard phone system from days long past. Your phone only knew how to do two things: connect to the switchboard and make noise. If you wanted to call your Aunt Mae, you’d pick up the handset and make noise with the ringer. After the operator answered, you’d give her Aunt Mae’s phone number, and she would cause Aunt Mae’s phone to make noise itself, and then she’d connect up your two phone lines. In this case, you contacted the switchboard (acting in this case as the “server”) and gave a specific identifier to the operator, and that person connected your phones. The protocol for this was well known, and the users of the telephone were able to interact with each other long before auto-switching was technically possible. Figure 1.4 shows how an API interacts with fr...