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

From: Markus Karg <>
Date: Fri, 19 Feb 2010 18:44:15 +0100



see inlined.


So I finally got the idea of this after I sent this last email. What you say
Markus makes total sense now.. and I DO agree with how it would work. I
totally love the idea of the client storing the state.


There are a few things however that I am hoping you can clear up.


The first is.. if the client is using my web cart service... and they need
to add an item, why make a call to the server to add that item? Why not just
simply build up their entire cart first with no calls to the server even if
their end user adds items... then once the user wants to check out, the
client sends the entire cart contents to my service at that point? Is that
the idea.. or are you saying that the client consuming my API should send a
POST /cart/<item id> every time their end user adds an item to the cart? I
am hoping you are saying.. send the entire cart at one time.. not every time
an item is added. Because I see no point in making a service API call to add
an item OTHER THAN perhaps to simply validate that the item being added can
be added. For example, if every time an item is added, we call the service..
the service can do a check on the inventory to see if the item is still in
stock. I think this might be kinda slow.. but at least it would give a real
time update of inventory and much faster response feedback. If an end user
takes 2 hours to fill up their cart.. any item might have been already
bought and out of stock... it would be much nicer to get faster feedback on
that issue. Otherwise, since the cart is stored on the client, there is not
much benefit of making a service call every time an item is added. But, with
HATEOAS.. I am assumging the ADD TO CART is a URI that is passed back by the
service when the user starts shopping.. so thus it would require a call
every time. Maybe it is better.. just not entirely sure in all cases that it
would be.

Nobody forces you to do a call to the server each time you add an item into
your cart. Unless you *want* to notify the server that the item is reserved
now, there is no need to. If you have all the information at hand on the
client side to fill the cart without further requests to the server side,
then you do certainly not need to do so. Even if you want to do HATEOAS,
there is no need to so so, unless the business process of the server
includes a dynamic rule that might change the possible URIs dependent of
what items you have added. Unless that is the case, those URIs stay fixed,
so you already have the URIs (received after the first server roundtrip). No
need to requests servers for nothing. :-)


If it's only about "reserving" an item in stock, you don't need to pass the
car. You could instead request a stock catalog once (a list of all available
items plus their URI plus their availability) at the beginning and POST
updates of single stock and pick from there. Whether you do the reservation
at once or later at the payment, is dependent on the business concept. If
you need to reserve them at once, you can just POST updates to their
particular stock URIs, sending just a small XML containing the new amount
plus a "eTag" to check whether the catalog is still valid. If yes, the
change will work. If not, the server will let you know and send back the
latest stock information to keep you updated. This involves more roundtrips,
but less bytes to transfer.


As you see, it is more about your business concept and creativity, less
about REST's constraints. :-)

Should each call to add an item send the entire cart? I would hope not. I
would guess, as I said above IF every add item requires a service call, it
should only be the one item going to the service, not the entire "growing"
cart of data. UNLESS (as I said above), each service request could check
that ALL items in the cart are still in stock.. again.. in my example above,
if I send ONLY the one item to add.. it can verify if it's in stock and give
quick feedback. That's fine. But if we send the entire contents, the service
could loop through all items, each time it's called and verify that all
items in the cart are still in stock. Would you recommend this? If so, what
about the growing size of data.. is that a potential issue, maybe not with
this web cart example, but perhaps with other types of data that could be
much larger..the more you add, the longer it will take for each request to
send more data and get it all back.

It depends on what you like to reach. You could e. g. have the items-in-car
modelled as their own document format, so you can just do a POST and upload
the single item. But again, only if you need to upload it at all. A
different technical approach would be the use of the PATCH method (which I
won't encourage as it is rather uncommon in RESTful applications) which
targets in uploading DIFFs, or using a different protocol, which is is
better suited that http (nobody says that REST must use http, it is just a
very, very good solution for most applications and I would never use a
different protocol unless needed -- like WebDAV if you want to use File API
clients instead of specialized clients).

Assuming either/both of the above are true (you send item or entire cart on
every request), I am assuming that the client's "state" of the cart is still
ok.. and any response back would simply be items that are no longer in stock
(in which the client would 'remove' those items from their stateful cart),
or the item(s) added to the cart (in which the client would 'add' those
items to their stateful cart)?

Yes, for example.

I am also wondering about man-in-the-middle issues.. where by if the client
sends all the stateful data every request.. I assume it must go encrypted to
avoid potential man-in-the-middle attacks.. perhaps this is a bit contrived,
but let's say someone intercepts the request and adds 5000 items right
before the "pay" step occurs. I am curious how the payloads are handled in
this respect.. but I suspect it's case by case basis.. if it needs to be
secure, the xml/json/<whatever> data gets encrypted before sent, and
decrypted once a response comes back?

If you have control of both sides, I would run the service through a VPN to
prevent this.


If you have no control of the client side, I would use HTTPS (or TLS with
any other protocol of choice) to encrypt the transfer.


But frankly, I am not a security or encryption specialist. As the
application server running you application will handle this, I just rely on
it's correct work and concentrate on the business model.

So I completely get the notion of stateless now in how you describe, and
like I said, it does make sense... for the most part. I totally would MUCH
rather each individual client store 500 bytes of data.. where they are
invidivual machines.. than my server having to have 256GB of memory or a
horizontal stack of servers with load balancer and such just to handle
10000's of users each with 500 bytes of data. Naturally this makes it FAR
easier on the server side to scale, and thus each server can handle WAY more
clients than the other way around. However.. I am


Seems you understood the principle now. ;-)


still having a hard time figuring out how to explain to consumers of my
service(s), that they will need to maintain all the state, pass it back and
forth, etc. I still feel that it will probably scare a lot of would be
developers from using my service. While the web cart is an example.. I have
a couple of ideas I am working on that I can't discuss right now, but will
potentially involve making some money from them.. and their are direct
competitors out there to the services I want to provide... and I am trying
to fathom how I explain to developers that in order to maintain a pure REST
api, they must do potentially a lot more work on their side to use my API.
By putting everything on the server as I and many others I think are doing,
the use of my API is extremely easy. It makes it very appealing to consumers
of my services that they simply make some get/post/put/delete calls with
minimal effort and voila! Trying to say "Hey.. I know those other APIs do
more for you than mine does..but mine is a PURE rest implementation..." I
think I am going to have a hard sale at best.. worse case very few if any
will want to use my service.

Don't explain to them that the target is a pure REST API. Tell them that the
service is much more stable or much cheaper thanks to this kind of API. Or
just don't tell them anything but just provide the SDK and wait what their
actual problems are. I do not see that it is a problem to keep a cart
updated on the client. After all, it is just a simple list of URIs, which
shouldn't be much of a problem for the average coder. ;-)


Also you could tell them that your API is much simple to use since they
don't need to fumble with SOAP and WS-* standards (ever had look how much of
them you need to get the same result?). REST is super compatible with every
client platform, while SOAP often is kind of a drama. Maybe this convinces
your coders?


Now, having said that, I know I can go either way. I can provide both if I
wanted to. There is certainly no reason why I can't give a pure REST
implementation, but also provide the one where I store the state on the
server side as well. But, doing something like that would most likely end up
everyone using the easier of the two, and I am in that situation that you
are saying "why would you want to do it this way"... why store state and
have to deal with scaling issues.

I'll give you one reason why. If the consumers of my service are one-off
clients.. a mobile phone, desktop app, etc.. then it is VERY easy to support
the pure REST api. Each individual device can house a little bit of memory
and my service is pure stateless...yay.. win win. BUT.. what if the consumer
of my API is a web site that is providing a user interface of their own for
potentially 1000's of users. If the end user is a store front (to use the
web cart service analogy), they now have to deal with scaling their web site
to handle those potential 10000's of users shopping on their site. In this
scenario, using my cart service makes no sense for them. I provide nothing
of value to those types of API consumders because I am shifting the "ease"
of scalability that they could avoid if my service dealt with the full
state.. back on to them. I can see where a web cart service that handles
state is VERY appealing to store front web sites. They no longer need to
worry about scaling to handle session fail over. My service is hugely
beneficial because I've alleviated a major headache for them. They can worry
about their pretty user interface and the products they sell, knowing that
my cart service provides them the inventory/cart storage/checkout process.
It's worth it to them to pay me a little bit to use that.

That is not a technical question but a question of fair business contracts.
If they don't want to serve 10.000 customers solely because of monetary
aspects, you can provide a compensation. There is no technical aspect, since
it is possible for their server to either host the carts or to forward that
task to their clients in turn (like using JavaScript or a JavaFX applet on
the client side keeping the cart's content). You just can scale back to the
originator of the workload. In fact, if your customer is a shop manager, and
he wants to server 10.000 customers, it obviously is HIS problem how he can
manage that. You can't run a front end without investments, either in a
front end server farm or in a software that offloads the task to the end
user's clients.


If you don't want that they have to deal with that, you could provide that
as a service for them and prefix your RESTful server with a carts load
manager server which caches the carts.

So I ask in this above scenario.. I guess I simply say "this is an HTTP API
that is not completely RESTful, but close to it..." maybe even explaining
why it's not 100% REST because I could not provide this service if it was?

Well, you could provide it, but I think you just don't dare to negotiate
with your contractors? ;-)

--- On Thu, 2/18/10, Markus Karg <> wrote:

From: Markus Karg <>
Subject: RE: [Jersey] JAX-RS == REST? Or not? (was Re: [Jersey] What HATEOAS
actually means)
Date: Thursday, February 18, 2010, 11:43 AM

Please see inlined. :-)


From: Kevin Duffey []
Sent: Donnerstag, 18. Februar 2010 12:03
Subject: RE: [Jersey] JAX-RS == REST? Or not? (was Re: [Jersey] What HATEOAS
actually means)


Hi Markus,


Thanks.. I understand what you mean more so now. I am still not quite sure I
see how asking a client to store their "cart" data rather than updating a
cart DB on the server side is any less restful. I say that because.. if we
can put an item in the cart and remove it from the available items that are
stored on the server side... why can't we keep the cart on the server side
as well? I understand the notion of statelessness.. but my understanding of
that is sort of how servlets and session cookies work.. stateful being the
session retains a cookie going back and forth... but moving that HttpSession
data to a DB table, while maintaining it's state.. the request/response are
stateless. From one request to the next, there is no state.. the logic in
the server side has to use something that comes in from the request to
figure out the stored state.. in my example, tying the authentication to a
user table, then from there being able to get the cart data/state from the
cart table based on that user. I guess I am unclear as to why this is


If you put the httpsession in a db table, the request/response is *not*
stateless but explicitly *stateFUL*, as to answer the request of a client
you must lookup (remember) the state of the client! If you like to add new
items in the cart, you must remember what is already in that cart. So you
cannot just reduce the stock size and send the client back an updated cart,
but first you have to go to your hard drive and search for that cart. That
IS by definition stateFUL. And as per of the definition of REST in
Fielding's dissertation, that is not what people would expect a RESTful
system work like, as stateLESS is a need here.


Don't get confused by the fact that the server stores stuff in the database.
That is *not* the "state". It is just application data. The "state" is the
current status of the shopping process of one particular customer (what he
has in his cart, whether he wants to buy more, go to the cash desk, or just
leave the shop).


In a stateless scenario, a server does not need to remember the current
shopping status of any *client* but just about the status of the stock
(which is a singleton, while actually there are lots of customers -- see the
difference?). It can concentrate on the status of the items in stock. This
is much less work. See it like a supermarket: It is rather easy to have an
overview of all the shelves. But it is rather complex to keep track of who
has currently what in his cart, what happened to the cart, etc.


If you are storing the cart's content on the server side, then you have
several problems (for simplicity as examples of possible problems


* Your system will be less scalable. Example: Think of all the shoppers that
grab a cart, start putting stuff into it and then leave the shop because
they changed their mind and don't want to actually buy the stuff. If the
cart is on the client, you can have virtually thousand of such
"non-shoppers" without any bit of place squandered on the server. You don't
have to do anything if one stops shopping. The cart just vanishes as the
client never will penetrate the server anymore. But if you have the
state-of-shopping for each client on the server, then you have to actively
remove it from your RAM and / or harddisk. At about 500 shoppers you might
run out of place, possibly. With client side carts (unless they actively do
something) there is virtually ZERO RAM / harddisk place needed for an
virtually unlimited number of (passive) clients.


* Complexity: It is much simpler to write a stateless server, as it must not
remember anything but it's own stock (but nothing about a particular
client's status).



Also, what drives me to drill down on this is some stuff I am working on
when I can spare some cycles... an eventual public service that might be
consumed by many developers. I don't know how I explain to them that my API
is a true RESTful API and as such, they must send me (and thus maintain) the
state on every request (depending on the URI chosen by the client... if they
choose Cancel, of course they don't have to send all the contents). I
suppose this is where I thought REST would be so beautiful.. using such an
easy HTTP call with minimal effort to add new items to the cart, get a list
of what is in the cart, delete an item from the cart. Having every developer
actually maintain and send me the cart contents every time a link is pressed
(that requires the "state" of the cart.. it's contents), seem's deterring to
me. I can imagine a lot of developer not understanding why this is done this
way. In other words, it almost seems like for me to provide a really
nice/easy RESTful API, I also have to provide some URIs that are NOT REST
based calls in order to maintain the state of a cart on the server side. I
am having a hard time grappling with this mixed API design.... on the one
hand, the server side keeps a DB of items that can be manipulated.. added to
the cart, updated, etc. On the other hand, the actual cart data for each
user is up to them (er..the developer consuming the API) to keep track of
send when needed, etc.


If you want to spare cycles, you should first think over what part of
cycles. If you want to spare CPU / HDD cycles, then you're better of if you
put the cart on the client, since it is the client's sole problem then and
the server is freed from it. If you want to spare client/server roundtrips,
then you should explane why you like to do so. As each "put this item in the
cart" action is just one roundtrip, I do not see how you could reduce that
by storing the cart on the server?


I do not understand what problem you have with explaining customers that
they must store state. This is typical in REST, so just tell them how it is.
Turn the idea around and look it that way: Why do you like to keep the cart
on the server? What benefit would this bring? If a developer doesn't
understand it then tell him the above examples with the lots of RAM you
would need to reserver on the server just for the cart of each possibly
orphaned client.


I do not see that you need a mixed API. Just drop the idea of keeping the
cart on the server. There is no real benefit from a cart on the server.


Again, remember the real worl shop: Are you (client) walking through the
shop with your own list in hand of what to buy, picking items and putting
them in your cart (so *you* have full control of what happens with the cart
and with the items on your list), or do you give the list to the manager,
waiting for all the stuff coming back, just saying "next one, next one"
after each provided item?



So let me throw this out there.. I'll probably get slammed for it..
especially if Roy reads it.. but perhaps while Roy's REST is sort of gospel
right now, perhaps this sort of hybrid use of REST is more useful than just
pure REST.. and I know you and others are not saying we CANT do this.. but
if the REST community is pushing the notion of REST.. and more and more
developers (like myself) start to understand what a truly RESTful API is and
doing it right, then some of the things I thought the REST I was doing
(which are probably more HTTP RPC) go away.. and now I can't offer a pure
REST API to do things like provide a public CART service that does NOT
entail the client side having to maintain the cart contents. I like the
"current" REST ways because it allows a much easier to use API than web
services. Using the simplicity of HTTP calls with authentication as many of
us do now, even those of us not using HATEOAS but publishing a SDK doc that
indicates ALL the urls a consumer can make at any point (as long as
authentication works).. I don't know.. it just seems to alleviate a lot of
the web services, SOAP, stuff like that that while not terribly difficult,
is not nearly as clean/pretty as this sort of ad-hoc REST a lot of us are
currently employing. So maybe rather than pushing this idea of pure REST on
the community, we should coin what I think you and/or Jan call an HTTP
API... perhaps come up with a better name for it.. or maybe not... I
honestly don't know if I would want to become a pure REST based API with
what I feel are now limitations of the meaning of a RESTful API. I like that
I can provide an SDK doc with clear info on calls, what to send in, and what
comes back under various circumstances. I like the idea of HATEOAS even
better, but with the same context of how I am using REST with Jersey today..
publish a SDK doc that indicates the first URL to go to, depending on
authentication you'll get back some subset of links you can then use. From
there, it goes on and on, but at least things like state that the service
provides can be contained in a dB on the server side and still provide a
very clean easy to use REST-like API and keep the client side relatively
easy as well.


Actually mixed APIs are not more useful, they just make it harder to
understand what part is working in what way.


I would really please you to provide an example why the cart *must* stay on
the server. What actual problem will it solve? What actual benefit will it
bring? If you really think that "some" http API is better than a "real" REST
API, why do you want it being part of JAX-RS (i. e. Java API for RESTful
WebServices) instead of e. g. Servlet API?

--- On Wed, 2/17/10, Markus Karg <> wrote:

From: Markus Karg <>
Subject: RE: [Jersey] JAX-RS == REST? Or not? (was Re: [Jersey] What HATEOAS
actually means)
Date: Wednesday, February 17, 2010, 9:53 AM

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