RE: [Jersey] Hypermedia Support is useless

From: Markus Karg <>
Date: Sun, 14 Feb 2010 18:32:52 +0100


> > Thinking several time over the alleged problem, I came to my personal
> > conclusion that either you or me did not understand that JAX-RS handles
> > this perfectly already, or I did not understand the problem itself, or
> > maybe the example workflow is just too simple.
> Glad you raise that issue, too. I am also not seeing what problem the
> proposal is trying to solve.

Well, in fact I understand the problem the proposal tries to solve (finding
out what workflows are on the server side and triggering them using http),
but I do not see that the solution is valid in respect of Fielding's
dissertation. Also server side workflows aren't RESTful at all, so the
problem itself is not RESTful. I just don't see that JAX-RS / Jersey should
solve this, as it hasn't to do anything with REST but just with people
wanting to do RPC via http.

> Even *if* the approach to, for example, starting a review process was
> the best way to go, I am notseeing why the client code should not
> simply extract the link from the response and create the next request.
> I find the proposal confusing because I do not see what the problem is.

The problem is that the client needs to know how to extract the URIs from
the content. With HTML this is not a problem, you can just pick all forms
and links, and with XML you can pick all XLinks, but what to do with Flash
and PDF for example? A solution compliant with Fielding's dissertation must
provide an API that is basing on content handlers, as the dissertation
enforces that the links are inside of the documents (as I explained in my
recent blog entry
means). So what I expect from JAX-RS is an API for the client side that is
extendible by content handlers. The handlers have to parse the content and
provide an interface to find out what they are good for and how to invoke

> > Let me explain:
> >
> > A real RESTful application needs no actions to solve workflows like
> > the above. In the real world, if a company lives that workflow and has
> > no computers, they will forward paper documents: Review Orders, Review
> > Results, Cheques, Receipts, Shipping Orders, Delivery Notes.
> Exactly. We should all emphazise (business-) document orientation and
> not focus on mappiing actions to links to pretend its RESTful.

Indeed. Many people do not understand that REST can be mapped 1:1 to
existing paper based processes and start to either invent fancy types of
documents (bad) or (even worse) try to call methods (like the proposal).
REST doesn't need neither actions nor methods. People must just correctly
map the existing business process to the electronic world.

> > The only difference is: The proposed new API is everything but
> > RESTful! It is a rape of the RESTful idea by people wanting to enforce
> > a RPC-style API ontop of REST
> Instead, the client programmer should *see* the network guts - as ugly
> as they may be. hides that we are dealing with remote
> calls

Even worse: is a complete misunderstanding of the RESTful
idea, as the disseration says that a workflow (like reviewing) must be
controlled (not invoked) completely by the client. This means, it will do
several calls to stateless servers and keeps track of the transaction, and
send and receive manipulated state. If the transaction has to fail, it will
just drop the document. But never will it be RESTful that a server
manipulates state! The dissertation clearly says that only the client stores
state. That's why I wrote in my blog entry that people should first read the
dissertation before discussing things: The complete HATEOAS discussion is
completely going into the wrong direction, as it targets in server
workflows, which just are invalid in REST.

> > -- but REST rest is about documents, not about methods (I am trying
> > to make this clear every day). It just makes no sense to directly map
> > command verbs to URLs in REST. If you like to do that, go to SOAP.
> > Also, the proposed API is less readable for people knowing the paper
> > process,
> Very much agree.

> > on both, the Java level (since it now implies command verbs where the
> > paper process had none and was solely based on transferring
> > representational state: Documents!) and the wire level. In fact I
> > wonder where REST is in your proposal? I do not see any representational
> > state getting transfered anymore, since many of the example methods
> > void-in or void-out or even both!
> Yes.
> I am not sure, of course, but it seems sometimes people take the
> hypermedia constraint to the extreme by very explicitly modeling the
> state transition aspect (mapping actions to links) where submissions of
> documents to processing resource would just do the job and be more
> naturally align with the paper process (as you said).

I do not think that people are taking the hypermedia constraint to the
extreme, but more I think that people have not understood what hypermedia
actually means: It is not about calling methods, it is about the sole fact
that inside of the representational state there is also the information of
what can be done with that. This has absolutely nothing to do with the idea
of calling a method. For example, if I receive a HTML document that has a
link in it, and the link allows me to make the server send me a modified
version of the document (like getting a verified one in contrast to having
an unverified before), then this is not a method call - but it is a state
transition, as I get back the same object, but in different state. And
exactly that is what Fielding had in mind: Let the client examine
transitions found inside of the hypermedia. Not letting the client finding
out methods to call. This is REST, not RPC.

> > Guys, that has nothing to do with REST. You just try to do RPC with
> > http. If you really like to implement that, then please remove the "R"
> > from the API's name, since that is not REST anymore.