By contrast, in a function-oriented API, there is more variability, and much more detail you have to learn.

Consider this table of examples:

... ...

/getAllDogs /getAllLeashedDogs

/verifyLocation /verifyVeterinarianLocation

/feedNeeded /feedNeededFood

/createRecurringWakeUp /createRecurringMedication

/giveDirectOrder /doDirectOwnerDiscipline

/checkHealth /doExpressCheckupWithVeterinarian

/getRecurringWakeUpSchedule /getRecurringFeedingSchedule

/getLocation /getHungerLevel

/getDog /getSquirrelsChasingPuppies

/newDog /newDogForOwner

/getNewDogsSince /getNewDogsAtKennelSince

/getRedDogs /getRedDogsWithoutSiblings

/getSittingDogs /getSittingDogsAtPark

/setDogStateTo /setLeashedDogsStateTo

/replaceSittingDogsWithRunningDogs

/saveDog /saveMommaDogsPuppies

... ...

11
To use an API made up of functions like this, you must understand what a dog is, and what its inherent
properties are, but you also have to learn a lot of detail that is specific to the functions of the API. That
detail has no clear structure or pattern you can use to help learn it, so there is a significant burden of
learning, and the knowledge you acquire will not help you with the next API you need to learn. There are
few, if any, common elements between APIs in this style.

A significant part of the value of basing your API design on HTTP and REST comes from the uniformity
that it brings to your API. In essence, when you use HTTP natively, you don’t need to invent an API at
all—HTTP provides the API, and you just define the data in your resources. In REST, this idea is called the
uniform interface constraint. In the World Wide Web, the significance of this idea is greater than just
making APIs easier to learn—having a uniform interface is part of what makes it possible to implement
universal pieces of software, like web browsers and search bots, that work with any website.

API Design Elements

The following aspects of API design are all important, and together they define your API:

• The representations of your resources—this includes the definition of the fields in the resources
(assuming your resource representations are structured, rather than streams of bytes or characters),
and the links to related resources.

• The use of standard (and occasionally custom) HTTP headers.

• The URLs and URI templates that define the query interface of your API for locating resources based
on their data.

• Required behaviors by clients—for example, DNS caching behaviors, retry behaviors, tolerance of
fields that were not previously present in resources, and so on.

12
Designing Representations
Many discussions of API design begin with an extensive discussion of URL design. In a data-oriented
model like REST, we think it is better to start with the representation design. We discuss URLs in the
section called Designing URLs.

Representation is the technical term for the data that is returned when a web resource is retrieved by a
client from a server, or sent from a client to a server. In the REST model, a web resource has underlying
state, which cannot be seen directly, and what flows between clients and servers is a representation
of that state. Users can view the representation of a resource in different formats, called media types.
In principle, all media types for the representation of a particular resource should encode the same
information, just in different formats.

Use JSON
The dominant media type for resource representations in web APIs is JavaScript Object Notation (JSON).
The primary reasons for JSON’s success are probably that it is simple to understand, and it is easy to map
to the programming data structures of JavaScript and other popular programming languages (Python,
Ruby, Java, and so on). It is now the de facto standard for web APIs, and you should use it.

While JSON is very good and very popular, it is not perfect for our purposes. One limitation is that JSON
can only represent a small number of data types (Null, Boolean, Number, String). The most common types
we have come across in web API design that are not supported by JSON are dates and times and URLs.
There are several options for dealing with this limitation—the simplest is to represent them as strings, and
rely on the context to determine which strings are just strings and which are really stringified dates or
URLs. We will discuss other options further in the book.

Keep your JSON simple

When JSON is used well, it is simple, intuitive, and largely self-explanatory. If your JSON doesn’t look as
straightforward as the example below, you may be doing something wrong.

“kind”: “Dog”

“name”: “Lassie”,

“furColor”: “brown”,

...

13
The JSON specification says only that a JSON object is a collection of name/value pairs—it does not
say what a name is, other than constraining it to be a string. In this example, the names correspond to
properties of a web resource whose representation is the enclosing JSON object. These property names
are sometimes called predicates, a term borrowed from the theory of grammar. Your JSON will be simpler
and easier to understand if you stick to the principle that the names in your JSON are always property
names, and the JSON objects always correspond to entities in your API’s data model.

Here is an example from the Facebook graph API that shows what JSON looks like when it doesn’t follow
this advice:

“{user-id-a}”: {

“data”: [

“id”: “12345”,

“picture”: “{photo-url}”,

“created_time”: “2014-07-15T15:11:25+0000”

... // More photos

},

“{user-id-b}”: {

“data”: [

Notice how user-ids appear on the left of the colon in the position where other examples of JSON we
have shown have a property name. The JSON name data also does not correspond to a property name in
the data model—it is an artifact of the JSON design. We think that JSON like this is more difficult to learn
and understand than the simple JSON in our first example and later in examples from Google and GitHub.
We recommend that you stick to the simple stuff.

14
 Include Links
Most problem domains include conceptual relationships in addition to simple properties. The
natural construct for representing relationships in HTTP is the link.

In years past, the use of links in APIs was strongly associated with the idea that API clients can and
should be written to behave like web browsers—meaning that they have no a priori understanding of the
data or semantics of any particular API, and their behavior is entirely driven by the contents of the data
returned by the server, particularly the links3. This idea is sometimes called Hypermedia As The Engine Of
Application State, or HATEOAS4 . It makes sense for a web browser to work this way because it would be
impractical to write a custom web browser for each site on the web. Clients that work this way are much
more difficult and expensive to write than clients that have built-in knowledge of a specific API. In addition
to being more expensive to build, generic API clients are usually also less satisfactory, especially clients
with a user interface, so this sort of API client is rarely built5, and the approach is viewed as impractical
by most people. A change in recent years has been the realization that the use of links brings a significant
improvement to the usability and learnability of all APIs, not just those that are designed to be consumed
by completely general-purpose clients.

Reprising the example introduced in the Foreword, assume that there is a relationship between a dog and
its owner. A popular way to represent relationship information in JSON looks like the following:

{“id”: “12345678”,

“name”: “Lassie”,

“furColor”: “brown”,

“ownerID”: “98765432”

3
Of course, JavaScript code that is loaded and executed by browsers often has specific knowledge of a particular API, so even the
browser only satisfies the constraints if you exclude the API-specific JavaScript it executes.

4
At least we think this is what HATEOAS means, and it has certainly been interpreted that way by many. We don’t find the de-
scription of HATEOAS in Fielding’s dissertation to be completely clear and unambiguous.

5
An area where we have seen successful generic API clients driven entirely by data is in the Internet of Things. In the IoT, we
have seen a large number of simple device types, each with its own API, where it is cheaper to build a single, data-driven client
than to build a custom client for each device.

15