RE: [Jersey] JAX-RS == REST? Or not? (was Re: [Jersey] What HATEOAS actually means)

From: Markus Karg <>
Date: Wed, 17 Feb 2010 18:53:58 +0100

There is a misunderstanding.


As Marc already explained, what is meant with "stateless" is "state of
workflow", not "state of resource". Example:


Your business process is that you want to fill your cart, and then go to the
cash desk. To "run" this by the client, the client must know whether you
already have paid or not (unless you would pay twice). This information is
not interesting for the server, as the supermarket is not interested in what
you bought after you paid and left the shop. But it is of interest, what
went out of stock or what the monthly income was.


So the server stores how many items are there of each article, and it also
stores the sum you paid. That information is "state of resource", but this
is not what our "stateless" discussion is about.


The discussion is about the fact that in the above workflow, the server
*must not* store the information what you have in your shopping cart, or
whether you have paid already. This information is stored solely by the
client. If the client puts more stuff in the cart, it will send the server
the current cart's content, the server "enriches" it be the new item AND BY
A "PAY BY VISA" LINK, and sends the more-filled cart content description XML
/ JSON back. Then it forgets about what it has done so far (despite the fact
that it reduces stock, see above). When you want to pay, you again upload
the cart's content to the server ("you put everything on the cash desk"),
VISA gets charged (thanks to the "PAY BY VISA" link that the server added to
the returned content!), and the server returns a document IN WHICH THE VISA
LINK *IS MISSING*, but in which a "Leave the shop" link is found. Then the
server forgets about this (but stores the sum you paid for later reporting).
Since the server removed the VISA link, the client has no more knowledge how
to pay, so you prevent that one goes to the cash desk twice. Thanks to the
"Leave the shop" link, the client can terminate the workflow.


As you can see, it is solely the client that drives the process and knows
about the previous and next steps. How? Since it stores the current
"workflow state" (here: the cart's content AND THE VALID LINKS) on behalf of
the client. Even if you shutdown the server meanwhile, you can reboot it, it
will not need to know anything about the workflow so far: The client know
it! The client inspects the links found in the latest response, and checks:
Can I order more (is there a link with the role "add more stuff in the
cart"?)? Can I pay (is there a VISA link?)? Can I leave the shop (is there a
"leave" link)? Exactly THAT is HATEOAS. :-)


About your authentication question: The above scenario will forget
authentication and re-authenticate with each call. So nothing will happen if
the server is shut down or load-balanced or fail-over'ed. Typical
non-RESTful scenarios (RPC) will have long-term authentication. If the
server is shut down, authentication is gone, and the workflow will most
typically rollback.


The other part of the discussion was about generic vs. specialized clients.
Jan wants to do spezialized clients, i. e. a client that know where to find
such links (besides in the entity aka document itself) and possibly the role
names of the links, while my idea is to have a generic client that can be
scripted from outside, so the script provides the information what role's
link is of next interest (like "genericClient.invoke("roleName");").





From: Kevin Duffey []
Sent: Dienstag, 16. Februar 2010 21:44
Subject: Re: [Jersey] JAX-RS == REST? Or not? (was Re: [Jersey] What HATEOAS
actually means)


Excellent!! +1 here too. I've bookmarked the links, I'll check back next
week to see any progress you make Felipe. I am really interested in seeing
how you (and others) are going about handling the HATEOAS responses.

I am also interested in understanding more from some of the other threads
about how the server does NOT maintain any state... per se... I guess I am
defining state differently perhaps, but to me, if you create/update
something using a URI, their is usually some database storing that data. If
I add a user via a POST, the XML/JSON I send is being stored in a DB. To me,
that is stateful. With the same authentication on subsequent calls, I could
maintain a sort of state. Same thing with a shopping cart. If I have a cart
DB table, and a user POSTs to a URI that adds an item to the cart, the logic
on the back end stores that item in the cart DB table associated with the
request (and the user making that request). Sure, the request/response
itself is stateless.. but the Authentication header allows me to verify (on
every call) a user and from that I can associate "state" using that user's
authenticated info and some other table(s) for the request specific
resourses. Am I missing some understanding about this process? Is it
correct.. or is there some better more RESTful way to do this?

So definitely want to follow the wiki and see how ya'll are workign thru
HATEOAS responses and maintaining a "quasi" state I suppose.


--- On Tue, 2/16/10, Felipe Gaścho <> wrote:

From: Felipe Gaścho <>
Subject: Re: [Jersey] JAX-RS == REST? Or not? (was Re: [Jersey] What HATEOAS
actually means)
Date: Tuesday, February 16, 2010, 3:46 AM

ok, I created two Jersey children pages:

"Samples" - that should be our catalog of examples

"Samples/PUJ" - my business scenario page..

I will try to be as fast as possible (probably in the weekend I find time).
As soon I have the first draft out there I ask your review - I plan to use
this page as sketchboard of my HATEOAS experiments. You all are invited to

Thanks for the opportunity, and feel free to move the pages on the Jersey
wiki if you prefer other names or locations.

On Tue, Feb 16, 2010 at 12:27 PM, Paul Sandoz <> wrote:

Hi Felipe,


A most excellent idea. Thank you for offering to do this, your contribution
is most welcome.


You can use the Jersey wiki. Anyone with an account can edit and add pages.



Santiago already put together a page for his ideas:


I am not sure if that page is suitable to link from for what you are
suggesting. I suspect we need a more general hypermedia page to link from
with a set of one or more cases from which solutions can be derived.



Also since you have implemented your business case i think you have a good
understand of what support Jersey can better provide to make it easier for




On Feb 16, 2010, at 9:56 AM, Felipe Gaścho wrote:

Hi there,

I would like to donate my business scenario as test bed for HATEOAS
implemented with JAX-RS.

What I need: a wiki page somewhere where I can describe my business case.
Then I start and other people can review and rewrite the parts they believe
wrong. We can have in short period of time a benchmark case. I will write
down only the business scenario and the suggested resources representation.

After that, everyone can implement that case in the way they believe better,
in which technology they believe better :)

Why to use my case instead of others?

1) Because the implementation of such project helps education in Brazil
2) Because it is generic enough to be adopted by other JUGs
3) Because it is open-source and there are already some implementation

* Of course, we can also think about a "catalog" where several people
contribute with business scenarios, and eventually the more complete one
will emerge from this brain storm.

If you like the idea, please point me the wiki I can start to write down the
spec of PUJ.

* I will try this anyway, bu if I have the community attention I will get
some extra push :)


   Felipe Gaścho

On Tue, Feb 16, 2010 at 9:50 AM, Paul Sandoz <> wrote:

Hi Kevin,


The Sun Cloud API is RESTful. Trust me :-)


We need to address your point about examples, with use-cases, when we have
more solid API details around hypertext and JAX-RS.


People are already developing hypertext applications using JAX-RS they are
just doing the work themselves. For example, Felipe is doing just that (he a
link on this list to some slides out recently). IIRC Marc, and he can
confirm or deny, has developed hypertext applications in the identity space
using JAX-RS, but i do not think those are public. And i am sure others have
developed similar examples.




On Feb 16, 2010, at 8:29 AM, Kevin Duffey wrote:

> Hopefully we can clarify this further with more concrete examples.


I hope soon.. I would really like to know the "right way" to build HATEOAS
apis. :D


I have read this extremely long thread, and am really really confused now as
to what is what. I thought the Sun cloud APIs was a completely restful API
design. However, this notion that the client maintains state has got me a
bit confused now. I would love to see some truly RESTful examples using
Jersey/JAX-RS.. how to implement for example HATEOAS in the present JAX-RS
such that I can claim my API is truly RESTful and that everyone on this
thread would agree on.






  Felipe Gaścho
  10+ Java Programmer
  CEJUG Senior Advisor
  Felipe Gaścho
  10+ Java Programmer
  CEJUG Senior Advisor