Web API Design - Crafting Interfaces that Developers Love
3
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.
