48
Date and time formats
The examples above use different approaches to representing time. There are probably more than a
dozen different standards for date and time representation, and the Twitter example doesn’t match any
that we know of. The format we see used most often is the one standardized by XML Schema, which is
a subset of the complex ISO 8601 standard. Bing seems to be using this. Unix had a wonderfully simple
and elegant time format that was based on the number of milliseconds elapsed since the beginning of
the epoch—dened to be the beginning of 1970, GMT. Foursquare seems to be using this format. This
terrically simple representation—a monotonically-increasing integer that was independent of location
and could be differenced to calculate time intervals—made an ideal time representation until it was
undermined by a very poor design decision that was made when implementing leap seconds in Unix.
The sad story is told here and elsewhere. Even though it is now compromised, this format deserves
consideration as a date and time representation.
Chatty APIs
It is a common myth that REST APIs are chatty. If your API is too chatty, it is because you designed the
wrong resources for your clients, not because you used REST. The myth of “REST implies chatty” probably
comes from the misconception that a REST API must look like a fully normalized relational database
schema. In a normalized design, there are separate resources for each distinct conceptual resource, like
orders, customers, accounts, and so on. If these are the only resources you dene, a UI client that wants
to display an order to a user may have to perform many GETs to retrieve the order, its line items, the
account, the customer that owns the account, and so on. Fortunately, no rule says that REST interfaces
must look like this, any more than there is a rule that a relational database schema must look like this.
Normalized schemas make updates simple, so one useful strategy for an API is to dene all the resources
that you would associate with a normalized schema, and give those resources both read and update
capabilities. You can then add as many read-only denormalized resources as you need to support efcient
clients. These denormalized resources are true REST resources also—they have meaning as entities, they
have URIs, and so on. Their state may overlap with the state of other resources, but this is not a problem,
and this API will be no less RESTful and much more useful than a normalized one. Other approaches to
denormalization are possible, but many have more complicated implications for update, analogous to the
update through a view problem of relational databases.
Pagination and partial response
Partial response allows you to give application developers just the information they need.
Take for example a request for a tweet on the Twitter API. You’ll get much more than a typical Twitter
app often needs— including the name of the person, the text of the tweet, a timestamp, how often the
message was retweeted, and a lot of metadata.