The API allows a client to perform a number of specific operations on these resources.

For example, given

a dog, retrieve information on the owner, and, given a person, retrieve all the dogs belonging to that
person. The common technique for exposing these functions in an API is to define a URI template that
the client can use to construct URLs from information in the resources (if you are not familiar with URI
templates, they are like URLs with variables in them that can be replaced with values to form a usable
URL). In the example above, we might describe the following URI templates:

https://dogtracker.com/persons/{personID}

https://dogtracker.com/persons/{personID}/dogs

https://dogtracker.com/dogs/{dogID}

These templates allow a client that has access to the data for the dog above to construct the following
URL to address the dog’s owner:

https://dogtracker.com/persons/98765432

Similarly, a client can construct this URL to address all the owner’s dogs:

https://dogtracker.com/persons/98765432/dogs

The HTTP methods GET, POST, PUT or PATCH, and DELETE can be used with these templates to read,
create, update, and delete description resources for dogs and their owners.

This API style has become popular for many reasons. It is straightforward and intuitive, and learning this
pattern is similar to learning a programming language API.

APIs like this one are commonly called RESTful APIs, although they do not display all of the characteristics
that define REST (more on REST later).

6
Introduction
Web APIs use HTTP, by definition. In the early days of web APIs, people spent a lot of time and effort
figuring out how to implement the features of previous-generation distributed technologies like CORBA
and DCOM on top of HTTP. This led to technologies like SOAP and WSDL. Experience showed that these
technologies were more complex, heavyweight, and brittle than was useful for most web APIs. The idea
that replaced SOAP and WSDL was that you could use HTTP more directly with much less technology
layered on top. Most modern web APIs are much simpler than SOAP or WSDL APIs, but preserve some of
the basic ideas of remote procedure call—which is not native to HTTP—implemented much more lightly
on top of HTTP. These APIs have come to be known as RESTful APIs. At Apigee, we advocate that you
should, as much as you can, only use HTTP without additional concepts.

Here’s Why:
When you design any interface, you should try to put yourself in the shoes of the user. As an API provider,
you may work on a single API or a small group of APIs, but it is likely that your users deal with many more
APIs than yours. This means that they probably come to your API with significant knowledge of basic
HTTP technologies and standards, as well as other APIs. Because of this, there is a lot of value in adhering
to standards and established conventions, rather than inventing your own. The HTTP specifications are
some of the best-written, best-designed, and most universally accepted standards that the industry has
ever seen—the chances of you inventing an alternative that will serve your users better are low. Not all
your users will have detailed knowledge of the HTTP standards, but making them learn the standard
HTTP mechanisms to use your API will be a better investment for them and for you than teaching them an
alternative you invented.

For example, if your API uses POST to create a resource, be sure to include a Location header in the
response that includes the URL of the newly-created resource, along with a 201 status code—that is part
of the HTTP standard. If you need to check that two people don’t try to update the same web resource
simultaneously, use the ETag and If-Match headers— that again is the HTTP standard. If your API allows
users to request data in different formats, use the HTTP Accept header.

If you want to provide alternatives to standard mechanisms that are specific to your API, go ahead, but do it in
addition to supporting the standard mechanisms, not instead. Do all of this and your users—especially those
that are knowledgeable of the workings of the web and are experienced with other APIs—will thank you.

This book is a collection of design practices that we have developed in collaboration with some of the
leading API teams around the world. And we’d love your feedback—whether you agree, disagree, or have
some additional web API design best practices and tips to share. The API Design group in the Apigee
Community is a place where web API design enthusiasts come together to share and debate design
practices. We’d love to see you there.

7
Web APIs and REST

The Job of the API Designer

The API’s job is to make the application developer as successful as possible. When crafting APIs, you
should think about design choices from the application developer’s point of view.

Why? Take a look at the value chain below. The application developer is the linchpin of the entire
API strategy. The primary design principle when crafting your API should be to maximize application
developer productivity and success.

Getting the design right is important because design communicates how something will be used. The
question then becomes— what is the design with optimal benefit for the application developer?

What is a web API?

A web API is the pattern of HTTP requests and responses that is used to access a website that is
specialized for access by arbitrary computer programs, rather than (or as well as) web browsers used by
humans.

What is REST?
REST is the name that has been given to the architectural style of HTTP itself, described by one of the
leading authors of the HTTP specifications. HTTP is the reality—REST is a set of design ideas that shaped
it. From a practical point of view, we can focus our attention on HTTP and how we use it to develop APIs.
The importance of REST is that it helps us understand how to think about HTTP and its use.

There are a few web APIs that are designed to use only HTTP concepts and no more. The majority of
modern APIs uses some subset of the concepts from HTTP, blended with some concepts from other
computing technologies. For example, many web APIs are defined in terms of endpoints that have
parameters. Endpoint and parameter are not terms or concepts that are native to HTTP or REST—they are
concepts carried over from Remote Procedure Call (RPC) and related technologies. The term RESTful
has emerged for web APIs that use more of the native concepts and techniques of HTTP than antecedent
technologies did, but also blend in other concepts. Many good APIs have been designed this way, and

8
in fact, this blended style is probably the most common API style in use. HTTP and REST are precisely
defined1, but the term RESTful is not—it is one of those “I know it when I see it” sort of concepts.

We are not purist about HTTP and REST—the effectiveness of the API is what matters—but we also
believe that all other things being equal, it is better to add as few concepts beyond just HTTP as possible.
If you do this, there will be fewer unique features of your API to be learned and managed over time. This
belief is really an expression of the more fundamental idea of Occam’s razor—use the fewest number of
concepts necessary to solve the problem. Quoting Antoine de Saint-Exupery, “perfection is achieved not
when there is nothing more to add, but when there is nothing more to take away.”

There are other reasons than conceptual minimalism for limiting ourselves to HTTP concepts for web
APIs. One of the most important characteristics that designers of distributed APIs strive for is minimizing
coupling between the client and the server. The measure of coupling is how easily either side can be
changed without breaking the other. Minimizing coupling is one of the most difficult things to achieve
in API design. HTTP’s track record of success in this regard may be unprecedented. Consider that the
web still supports HTTP clients that were written 20 years ago, showing just how effectively HTTP
has decoupled clients from servers. The analysis and description of how HTTP achieves this level of
decoupling is one of the highlights of the REST dissertation, and decoupling is one of the primary reasons
to be interested in HTTP as a platform for APIs in the first place. One reason that it is controversial to
layer concepts from other models on top of HTTP—for example, those that derive from RPC—is that they
tend to undermine the loose coupling quality of the HTTP design. This is another important reason to
stick with just HTTP.

In the remainder of this book, we explore how to design web APIs using only the inherent concepts of
HTTP. We use the term REST API to mean web APIs that have this quality2.

1
Sometimes you will hear people claim that REST is not precisely defined—this is not true.

2
Since REST is an architectural style, it should be possible to invent APIs in this style that are totally independent of HTTP. Such
APIs are outside the scope of this book.

9
HTTP and REST: A Data-oriented Design Paradigm
A REST API focuses on the underlying entities of the problem domain it exposes, rather than a set of
functions that manipulate those entities. Following the example introduced in the Foreword, suppose our
problem domain is tracking dogs and their owners. Primary entities we might expose would include:

• The collection of known dogs. Its URL might be https://dogtracker.com/dogs.

• Individual dogs. They each have a unique URL. We will discuss the format of their URLs in a moment.

We also need something analogous for owners.

Why is a data-oriented approach useful?

Given the URL of an individual dog and knowledge of how the HTTP protocol works, you already know
how to do quite a few things. For example, you know how to retrieve the details of the dog using the GET
method, delete the dog using the DELETE method, and modify properties of the dog using the PATCH
or PUT methods. To use these successfully, you have to understand the properties of a dog, but the
mechanics of the operations are already known to you. If the dog has related entities, like an owner or a
medical history, you can manipulate those entities in a similar way.

Similarly, given the URL of a collection of dogs, you already know how to create new ones, using the POST
method, and find existing ones, using GET. You may have to learn how to filter the collection to narrow
your search, but in a well-designed API, it is likely that is done using query parameters added to the URL
of the collection.

10