192 | Chapter 7: REST, Resources, and Web Services
return, but cannot interpret. The concept of URIs as opaque values originates not
with Roy Fielding, but with Tim Berners-Lee:
The only thing you can use an identifier for is to refer to an object. When you are not
dereferencing, you should not look at the contents of the URI string to gain other
information.This is a controversial idea, and the REST community is split over it. URIs have
evolved as a hybrid of opaque and transparent names. Particularly with human-
friendly (“pretty”) URIs, people naturally expect to be able to interpret and modify
the URIs that they use. Upon receiving a 404 Not Found for John Smith’s index of
papers published in 1997 athttp://example.edu/~jsmith/papers/1997/index.html,itis
reasonable to expecthttp://example.edu/~jsmith/, if it exists, to be somehow associ-
ated with John Smith.
URIs tend to self-organize into a hierarchy, in no small way due to their provenance
as filesystem paths. It is not a good idea to break users’ expectations in this regard.
Although it may or may not be desirable for clients to always respect name opacity
(by only using URIs for dereferencing), it is certainly undesirable for servers to force
name opacity by creating inscrutable naming schemes.
Those who believe names should be opaque generally state that relationships
between URIs should be mined through links between resources. If a person (or
machine) retrieves a list of users (GET /users), the response would contain links to
each user in the list (/users/1,/users/2, ...). Commonsense as this may seem, espe-
cially for a machine-consumable service, there are prominent RESTful web services
(such as Amazon S3, which we will examine later) that do not use links at all.
URI templates, described in an Internet Draft (http://www.ietf.org/internet-drafts/
draft-gregorio-uritemplate-02.txt), are a promising new hybrid between link-based
and hierarchical navigation. A URI template provides a structured pattern for URIs,
so that they make sense as hierarchies but can still be treated as opaque:
http://example.com/carts/{cart_id}A client application could use this template to generate a URI for a shopping cart.
The primary advantage of URI templates is that they are structured; the template can
be provided as an input to a web service client, rather than hardcoding the URI into
the application.
The bottom line is that opacity as a hard-and-fast rule does not always make sense.
Sometimes a graph of data accessed through links makes sense; sometimes a struc-
tured naming system might be more fruitful.
The advantages of a structured name system are apparent with algorithmic
resources, which represent the results of a calculation. These resources are typically
infinite in number, and are accessed through names likehttp://example.com/search/
banana. In this case, it can make more sense to allow both the client and intermediaries
to infer semantics from the URI.