RE: [Jersey] What HATEOAS actually means

From: Markus Karg <>
Date: Tue, 16 Feb 2010 18:45:10 +0100

Yes, as I just have read (had to stop working yesterday) the RESTmaster
enlighted me that *some* headers are indeed valid. The problem is two
things: (a) The Link header is not yet part of the http standard, so
"officially not existing". A foreign client would not expect to check any
"officially not existing" header, so it would be incompatible with the
proposed solution. (b) Content-Location is only valid, as he explained, for
the URI of THIS content, so cannot be used for anything else, same for
Location which is only valid for redirections. That means, foreign clients
will never check those headers. So yes, it is valid to have links in that
headers, but it will lead to incompatible clients. And the target of REST is
-as Fielding pointed out in his dissertation- that any client can talk with
any server. When using standardized headers for things they are not expected
to be used for, or when using non-standardized headers, this will fail. I
agree that the link header is the perfect solution if the links cannot be
put inside of the entity (this is the explanation of the existence of the
header, according to the RFC) -- but not as long as it is not part of the
http standard.


So in fact I do not agree that I am "wrong" in sum, but only in the specific
question of whether there can be links in headers. Sure there can be. But it
will be of no benefit for a system that tends to be compatible with foreign
clients, which is part of the definition of REST.


As you see, I just think in wider dimensions, where "wrong" in the inner
sense might be "not so wrong" in the wider sense. ;-)


From: Paul.Sandoz_at_Sun.COM [mailto:Paul.Sandoz_at_Sun.COM]
Sent: Dienstag, 16. Februar 2010 07:36
Subject: Re: [Jersey] What HATEOAS actually means


Hi Markus,


Respectfully, you are still wrong.


The current Link draft specification and the HTTP specification are quite
clear on the matter. And Roy, in another email, has also clarified this too
with respect to those specifications:


  Link is part of the representation metadata (that's its whole reason to

  Content-Location is representation metadata for the URI of this content.
  Location is a response header used as part of the redirect aspects of


  All three are data for describing transitions from here to there, when

  according to the HTTP standards, and thus are part of the hypertext as far
  as REST is concerned. This is necessary for the support of hypermedia
  representations in a format that does not allow embedded links or
  and for a lot of other reasons that I have no time to describe right now.


I consider that this particular aspect of hypermedia is now suitably
clarified and requires no further discussion on this list.




On Feb 15, 2010, at 7:41 PM, Markus Karg wrote:



sorry but I have to insist on what I wrote on my blog:


"There is only and exactly one valid implementation of HATEOAS: Having links
inside of the document."


Why? First of all, because it is exactly written in both, Fielding's
dissertation Chapter 5.2, and nine years later in that blog
entry he wrote. If you don't believe me, just ask him (nothing else I want
to reach: stop guessing and discussing, just ask the RESTmaster himself!).
Second, because REST is an abstract pattern, just as HATEOAS is. It is
unrelated to http. According to Fielding, it must be possible to use do the
same RESTful application on different protocols without modifying the
document. If you send state information outside of the document, e. g. in
the headers, then this will not work when using a protocol that has no such
thing like headers.


HATEOAS is not about sending state information anywhere, it is about sending
stahte information in the MEDIA. But headers are not media, only the
document is. It is true that http allows to send information in headers
(never said something against that), but that is not part of the MEDIA. And
after all, the H in HATEOAS is from "HyperMEDIA" not from


Also I never said that http forbids to send links in headers. This is valid
http. But it is neither HATEOAS nor REST.






From: Paul.Sandoz_at_Sun.COM [mailto:Paul.Sandoz_at_Sun.COM]
Sent: Montag, 15. Februar 2010 11:46
Subject: Re: [Jersey] What HATEOAS actually means


Hi Markus,


Thanks for getting involved in the discussion.


The following statement is in your blog wrong:


  There is only and exactly one valid implementation of HATEOAS: Having
links inside of the document.


The definition of an HTTP entity is as follows:


   Request and Response messages MAY transfer an entity if not otherwise
restricted by the request method or

   response status code. An entity consists of entity-header fields and an
entity-body, although some responses

   will only include the entity-headers.


Entity-header fields can consist link headers:


   A means of indicating the relationships between resources on the Web,

   as well as indicating the type of those relationships, has been

   available for some time in HTML [W3C.REC-html401-19991224
-html401-19991224> ], and more

   recently in Atom [RFC4287 <> ]. These
mechanisms, although conceptually

   similar, are separately specified. However, links between resources

   need not be format-specific; it can be useful to have typed links

   that are independent of their serialisation, especially when a

   resource has representations in multiple formats.

   To this end, this document defines a framework for typed links that
   isn't specific to a particular serialisation or application. It does
   so by re-defining the link relation registry established by Atom to
   have a broader domain, and adding to it the relations that are
   defined by HTML.


The following are also pertinent to the general discussion:


Roy states at the end of his blog in the link above:


  The API can compensate for the use of POST by responding with the
statement that the client should refresh

  its representation of the larger resource state. In other words, I would
return a 303 response that redirected back

  to the VM status, so that the client would know that the state has


In the experimental prototype the client compensates by processing a Link
header of a link relation "refresh".


What we have been currently experimenting with is one particular *pattern*
of hypermedia [*], one that has also been investigated with the API for the
Sun Cloud (alas which IIRC may be no more).


We need to come with a number of patterns that can be applied to use-cases
and have corresponding prototype implementations and from all that we will
be able to hopefully define really good client and server hypermedia API




[*] What ever you might think of it one thing it is not is RPC.



On Feb 14, 2010, at 4:32 PM, Markus Karg wrote:

For those interested in the current hypermedia discussion, I'd like to point
you to my latest blog entry about "What HATEOAS actually means". It might be
interesting to follow its links into Fielding's dissertation so everybody
understands what the recent discussion was / is about. It also explains why
I think that the current Jersey proposal is invalid, since it is not
implementing HATEOAS from the view of the dissertation but more from a
pragmatic aspect of doing RPC via http.