Re: [Jersey] What HATEOAS actually means

From: Paul Sandoz <Paul.Sandoz_at_Sun.COM>
Date: Mon, 15 Feb 2010 17:27:12 +0100

>> IMHO the server-side is rather simple, but i would say that :-),
>> and it can be summarized in the following four steps:
> Yes, server side is simple. Just get the HTTP straight (JSR311 is
> quite good at that) and jot down your resource implementations.
> Server side can even be as simple as a shel script started by inetd
> (hope I am not mixing up the name here).

Perhaps there may be some misunderstanding i was referring to the
server-side support for the particular hypermedia pattern i described
in the 4 steps.

>> 1) A resource, R say, has a bunch of sub-resources that can modify
>> the state of R.
> Why is that important?

I am attempting to formally define the hypermedia pattern as supported
by the simple link header-based hypermedia plugin on the server-side
and i am most emphatically not trying to formally define hypermedia in

>> 2) A client may perform a GET on R to retrieve the representation
>> of R, the entity,
>> and "be" in the current application state, A say.
> Yes - and 'not quite'. The model is that only some resources 'are
> for' application state When they are retrieved, they send a
> reprsentation (roy calls it the primary representation) which might
> instruct the cient to follow a number of other links until a steady
> state is reached. The steady state is the application state and a
> steady state may be a collection of several representations. That's
> what Roy calls the 'current set of representations'.

Right, no argument there but it is a generalization of what is stated
in 2) for the prototype.

> This is less important from a server side POV but essential for the
> client side programming model.
>> 3) That entity will consist of a set of Link headers, L, say, each
>> of which contains a link to
>> a sub-resource in 1) and a relationship type. The set L
>> corresponds to the set of valid
>> application states the client may transition to given the
>> current application state A.
> Huh? Who cares? The steady state contains representations that have
> media types and these types tell the client what it can achive by
> traversing the offred transitions. Some links might be to other
> servers, some might be to other resources outside the current
> resource's URI space and some might be below that URI space.

Right, and again that is mostly a generalization of what is stated in
3). And again, i am describing how the prototype works not hypermedia
in general.

Here is the "kicker" with respect to link headers: a representation is
a response that is an entity that consists of entity header fields and
an entity body. And link headers may link to the cases you describe

    [...] links between resources need not be format-specific; it can be
    useful to have typed links that are independent of their
    especially when a resource has representations in multiple formats.
    The Link entity-header field provides a means for serialising one or
    more links in HTTP headers.

> The rest is up to the media types and the choices of the server. I
> don't think a framework should affect/influence these design issues
> in any way.

Link headers provide a useful alternative to that of media types for
certain cases of hypermedia support.

> I'd rather like to see plugins for individual media types that make
> extracting stuff from representations (of them) easier.

I would like to see that too. In fact what i really want to see from a
client API perspective are proxies to instance of Java types for media
types that can extract, from the contents, proxies to links with
relations. In addition to proxies to Link headers.

>> 4) The client may process one of the link headers of L to
>> transition from A to a new application
>> state, B say. As part of that transition process the client will
>> refresh the it's application state
>> of R.
> Again: huh? Who cares? If the server wants the client to refresh, it
> can do so by sending a redirect or 409 or 303 maybe.

Yes, i am just stating how it is currently done. It is easy to change
the current implementation to support a 303 instead.

> HTTP covers all that already. Besides, if you use information of a
> steady state, the freshness should be taken into account anyhow
> (Look at TTL header information and.or do a conditional GET - or
> have the server sort stuff out)

Agreed, this is a general problem when clients make changes to
resource state.

> No, I do not think thatthe framework needs to deal with all this at
> all. Just implement HTTP (but only! HTTP) correctly on the client
> side.

The hypermedia pattern i outlined above can be implemented in Jersey/
JAX-RS server (client is a separate issue) now without any additional
APIs, but with a simple plugin it is possible to aid the developer for
this particular pattern. All i am trying to do in this and last email
is explain how this hypermedia pattern works.

> Understood. Sun Cloud API is not a REST API, is it?

Yes it is.

> I do not image (though have not looked at it) that they provide a
> bunch of media types that specify the semantics, do they? If they
> don't, it is at best an HTTP-based API.

Note that the Sun Could API makes use of "controller" URIs (or
"action" resources) but does not utilize Link headers for hypermedia.

However, as the prototype demonstrates Link headers can serve as an
alternative to, but not a replacement of, media types for hypermedia.