RE: [Jersey] What HATEOAS actually means

From: Markus Karg <>
Date: Mon, 15 Feb 2010 22:41:06 +0100

> > I think the problem is the opposite: We are discussing things that
> just are
> > not REST, while our job actually is to define a Java API for REST. So
> we
> > cannot discuss the example, as it is not RESTful. It wouldn't make
> sense. We
> > all are graduated, so we should be possible to discuss abstract
> application
> > architecture without the need to discuss particular use cases.
> Shouldn't we?
> Sure, but ultimately people want to solve real and concrete problems.

They they should write applications but not discuss frameworks, as
frameworks are always abstract solutions for abstract problems. ;-)
> >> Let's look at the purchase order example again. Let's say I have
> 300-
> >> field order, which is not uncommon in real examples.
> >
> > If it is not common, why using it as an example then?
> not uncommon?

Sorry, I have read "is not common". My fault.

> > The example is wrong. Why do you want to upload the order while the
> client
> > actually still is adding items?
> Because I may send an order today, and tomorrow change my mind and
> want to add something else?

GET order/id -- will return the order
PUT order/id -- will update the order by sending all changes in one step

You still have just two PUTs, but not 300. Or will you change your mind 300

> > And why do you want to have items be part of
> > the order instead of each being its own resource instance (Fielding
> also
> > told us to not build aggregates where references will server pretty
> well).
> Product are resources, ordering X quantity of product Y is really part
> of an order and not something interesting outside of a particular order
> (i.e., not a resource).

Sorry I have to disagree. Just as a database would store it in different
tables, those are different resources. In fact, ordered items are typically
a sub item of orders and such can be POSTed easily. Why not just applying
database normalization rules to resources? Informatics don't change just
because of a different technology to implement it. :-)

> > As long as the client is in the process of adding items, the state of
> the
> > workflow is not changing. So why pushing something up to the server?
> For
> > what?
> > Do you see what I mean with "the example is not the problem, since it
> is not
> > RESTful"?
> I don't, sorry. Placing an order today, and changing it tomorrow has
> nothing to do with being RESTful. It's just what real-world systems
> have to cope with.

Here we are at the core point! Do you like to discuss REST or do you like to
discuss your actual daily problems? I never said that for your actual
problems a RESTful API is the right solution!

> As engineers, we can't just say "we won't implement
> that because it's not RESTful".

Well... actually we can, and it is what makes our lives so much easier in
ten years, when we will be happy that we did not just do a pragmatic

A RESTful solution to your problem is to (a) normalize your tables /
resources to have ordered items get referenced but not contained and (b) to
upload only once per change set but not per each single change. That IS your
solution, it IS practical, and it IS RESTful. See the difference? Don't try
to force RPC just because you're used to do it.

The state change is NOT the new item! That is ONLY a CONTENT change (not
EVERY content change is a state change!). A state change would be that you
have paid or shipped. As long as the order is in the state of item
selection, it is still the same state. Don't mix up state and content. They
are related, but not identical.

> >> I don't think these
> >> buttons/actions make any system more or less REST (although I
> perfectly
> >> understand how they can trigger these long discussions :)
> > Well, as I tried to point out in my blog, the definition of REST is
> > (luckily) not dependent on what your or me or anybody THINKs, as
> there is
> > exactly one and only one exact and unambiguous defition given in the
> > dissertation by Mr Fielding. And that definition does not contain
> actions or
> > buttons, so they are NOT RESTful. If you still doubt it, read
> Fielding's
> > blog
> driven
> > that points out that actions of any form are NOT RESTful as they are
> RPC.
> Having a discussion with Roy would be interesting. He may indeed think
> this is not RESTful, but I'm interested in understanding the reasons.

So ask him. :-) Why not?

> But, more importantly, understand how frameworks like Jersey can help
> developers with HATEOAS.

As I pointed out several times: Add a plug in mechanism that allows to add
link list in the body / read the link list from the body. That supports
HATEOAS and is 100% REST. But it is useless as a client / server that is
able to produce / consume this MIME type typically will already be able to
add / read links from within. So it us just useless, as I said before.

The problem with HATEOAS is *not* that the framework does not support it,
but that programmers do not understand it (as can be seen in this whole
discussion which is not about the API or the framework but solely about REST
vs. RPC and "I think that..." vs. "Mr Fielding said"). So if you want people
to do HATEOAS, let's write a blog or article about how to do CORRECT
HATEOAS. Then they don't need a framework. They just call for a framework
because they think they don't need to understand what HATEOAS is then!