Chapter 10 ■ http ServerS17 7Dr. Fielding is specific that “REST is defined by four interface constraints,” which he briefly enumerates at the end
of section 5.1.5 of the dissertation.
• Identification of resources• Manipulation of resources through representations• Self-descriptive messages• Hypermedia as the engine of application stateMany service designers, wanting their designs to run with the grain of HTTP’s design instead of against it, have
aspired to the creation of services that can properly earn the accolade “RESTful.” Dr. Fielding is at pains to object that
most of them do not. Where do they go wrong?
The first constraint, “identification of resources,” rules out nearly all traditional forms of RPC. Neither JSON-RPC
nor XML-RPC (see Chapter 18) exposes resource identities at the level of the HTTP protocol itself. Imagine a client
that wants to fetch a blog post, update its title, and then fetch the post again to see the difference. If these steps were
implemented as RPC method calls, the methods and paths visible to HTTP would be as follows:
POST /rpc-endpoint/ ® 200 OK
POST /rpc-endpoint/ ® 200 OK
POST /rpc-endpoint/ ® 200 OK
Presumably somewhere inside the body of each POST, each of these requests names something like “post 1022”
as the specific resource that the client wanted to fetch or edit. But RPC makes this opaque to the HTTP protocol. An
interface aspiring to REST would instead use the resource path to specify which post was being manipulated, perhaps
by naming it /post/1022/.
The second constraint, “Manipulation of resources through representations,” prohibits the designer from
specifying an ad-hoc mechanism, specific to their service, by which the title must be updated. That, after all,
would require client authors to wade through service-specific documentation every time they wanted to learn
how to perform an update. In REST, there is no need to learn a specific trick to changing a post’s title because the
representation of a post—whether it uses HTML, JSON, XML, or some other format—is the only form in which
either reads or writes can be expressed. To update a blog post title, a client simply fetches the current representation,
changes the title, and submits the new representation back to the service.
GET /post/1022/ ® 200 OK
PUT /post/1022/ ® 200 OK
GET /post/1022/ ® 200 OK
The idea that fetching or updating a dozen resources must require a dozen round-trips to the service is a
sore point for many designers and a strong temptation to make pragmatic exceptions to the architecture. But the
advantages of REST, when followed, are symmetry between the operations of reading and writing a resource and the
exposure of meaningful semantics in the HTTP protocol. The protocol can now see which requests are reads and
which are writes, and if GET responses include the right headers, then caching and conditional requests become
possible even when programs are speaking with each other without a browser involved.
Explicit caching headers bring us to the third constraint, “self-descriptive messages,” because such headers make
messages self-documenting. The programmer writing a client does not need to consult API documentation to learn,
for example, that /post/1022/ is in JSON format or to learn that it can be cached only if conditional requests are used
to assure that the cached copy is up-to-date, while a search like /post/?q=news can be served directly from cache for
up to 60 seconds after retrieval. This knowledge is instead declared afresh in the headers of every HTTP response that
is transmitted.