RESTful Web Services - Java SOA - page 478

HTML in a browser, though that is perhaps the most popular form. Fielding's site defines hy-
pertext as “the simultaneous presentation of information and controls such that the informa-
tion becomes the affordance through which the user (or automaton) obtains choices and se-
lects actions.”
The idea of “hypermedia as the engine of application state” is mentioned, but not elaborated
upon, in section 5.1.5 of Fielding's dissertation. As a result, it is probably the least understood
aspect of REST, though it is also one of its most important tenets. Despite Fielding's brevity,
it is clear what this means: every document returned by the server will include all the URIs
to any next step. That is, all possible application states that the user can transition to from the
current state are represented as resource URIs (hypermedia links). Application state is driven
(transitioned to a next state) by selecting and following a URI.
On his website, Fielding recently restated the case that hypertext is a constraint: “if the engine
of application state (and hence the API) is not being driven by hypertext, then it cannot be
RESTful and cannot be a REST API. Period. Is there some broken manual somewhere that
needs to be fixed?” ( http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven )
In many web applications, developers use cookies to retain state on the client. But cookies,
which are a function of HTTP, are considered unreliable and insecure, and they side-step
the semantic constraints of REST. Therefore, using cookies to keep state on the client (login
status, preferences, etc.) is explicitly disallowed by the Fielding dissertation (section 6.3.4.2).
This constraint is frequently ignored, however, in “RESTful” framework implementations in
the real world, not the least of which is JSR 311, which includes the @CookieParam annotation
to allow a provider to extract information from cookies, as well as access to the Cookie class.
So there are competing degrees of “purity” among REST practitioners.
REST really takes issue with cookies because they carry state and are intended to be sent to
the server in future requests. Because some state is set in the cookie, the application avoids
representing all possible next-state transition possibilities directly in the hypertext.
It's fine to use cookies if you need to. We've been using them for many years. There are loads
of popular websites that use cookies. Just don't call that application RESTful.
So in REST, how do you keep state for something like a shopping cart? Fielding's suggestion,
instead of using cookies to identify a set of cart products within a server-side database, is to
define the semantics of the products within hypermedia data formats, so that the user can store
selected items client-side and use a URI to check out. To restate the point, the URI serves as
the ID of the resource. Any information item that can be named can be a resource. “Bob's
shopping cart on Tuesday at 9 a.m.” is a valid resource. Hypermedia as the engine of applic-
ation state (sometimes abbreviated HATEOS) is one of the key tenets of REST, and we will
revisit this idea throughout the chapter.