Web API Design – Crafting Interfaces that Developers Love

Introduction

If you’re reading this, chances are that you care about designing Web APIs that developers will love and that you’re interested in applying proven design principles and best practices to your Web API.

One of the sources for our design thinking is REST. Because REST is an architectural style and not a strict standard, it allows for a lot of flexibly. Because of that flexibility and freedom of structure, there is also a big appetite for design best practices.

This e-book is a collection of design practices that we have developed in collaboration with some of the leading API teams around the world, as they craft their API strategy through a design workshop that we provide at Apigee.

We call our point of view in API design “pragmatic REST”, because it places the success of the developer over and above any other design principle. The developer is the customer for the Web API. The success of an API design is measured by how quickly developers can get up to speed and start enjoying success using your API.

We’d love your feedback – whether you agree, disagree, or have some additional practices and tips to add. The API Craft Google Group is a place where Web API design enthusiasts come together to share and debate design practices – we’d love to see you there.

Are you a Pragmatist or a RESTafarian? 

Let’s start with our overall point of view on API design. We advocate pragmatic, not dogmatic REST. What do we mean by dogmatic?

You might have seen discussion threads on true REST – some of them can get pretty strict and wonky. Mike Schinkel sums it up well – defining a RESTafarian as follows:

“A RESTifarian is a zealous proponent of the REST software architectural style as defined by Roy T. Fielding in Chapter 5 of his PhD. dissertation at UC Irvine. You can find RESTifarians in the wild on the REST-discuss mailing list. But be careful, RESTifarians can be extremely meticulous when discussing the finer points of REST …”

Our view: approach API design from the ‘outside-in’ perspective. This means we start by asking – what are we trying to achieve with an API?

The API’s job is to make the developer as successful as possible. The orientation for APIs is to think about design choices from the application developer’s point of view.

Why? Look at the value chain below – the application developer is the lynchpin of the entire API strategy. The primary design principle when crafting your API should be to maximize developer productivity and success. This is what we call pragmatic REST.

Pragmatic REST is a design problem 

You have to get the design right, because design communicates how something will be used. The question becomes – what is the design with optimal benefit for the app developer? The developer point of view is the guiding principle for all the specific tips and best practices we’ve compiled.

Nouns are good; verbs are bad

The number one principle in pragmatic RESTful design is: keep simple things simple.

Keep your base URL simple and intuitive

The base URL is the most important design affordance of your API. A simple and intuitive base URL design makes using your API easy.

Affordance is a design property that communicates how something should be used without requiring documentation. A door handle’s design should communicate whether you pull or push. Here’s an example of a conflict between design affordance and documentation – not an intuitive interface!

A key litmus test we use for Web API design is that there should be only 2 base URLs per resource. Let’s model an API around a simple object or resource, a dog, and create a Web API for it.

The first URL is for a collection; the second is for a specific element in the collection.
/dogs                         /dogs/1234

Boiling it down to this level will also force the verbs out of your base URLs.

Keep verbs out of your base URLs

Many Web APIs start by using a method-driven approach to URL design. These method- based URLs sometimes contain verbs – sometimes at the beginning, sometimes at the end.

For any resource that you model, like our dog, you can never consider one object in isolation. Rather, there are always related and interacting resources to account for – like owners, veterinarians, leashes, food, squirrels, and so on.