Re: [Jersey] Jersey's (experimental) approach to support hypermedia constraint

From: Paul Sandoz <Paul.Sandoz_at_Sun.COM>
Date: Wed, 10 Feb 2010 18:40:58 +0100

On Feb 10, 2010, at 4:21 PM, Jan Algermissen wrote:
> The only RESTful way to approach this is
> - GET /orders/2
> - dispatch on whatever media type we received (or on available
> headers)
> - if have-link-header 'pay' OR media type == application/order AND
> have pay-link in the representation THEN (and only then)
> - do a POST on the target of the pay link (we know this from
> corresponding spec (and maybe form in representation))

The intent of the proxy implementation is to do something similar to
the above (but only link headers are currently implemented). But it
still needs better error handling.

Have you tried playing around with the example?

> - GOTO handle next state
> - if media type == [something else]
> - try out some other rule to persue the goal of 'paying'
> - if 4xx
> - handle 4xx
> ....
> The issue is that REST does not allow us to view one particular
> representation as the 'correct' server behavior and the others as
> 'failures'. Even 4xx responses must be considered part of the normal
> conversation between client and server.
> It may be hard to accept, but anything else would not be REST. With
> the result that server owners have to know what their clients are
> assuming besides hypermedia semantics.
> My deepest concern is to get this point across to developement teams
> (that do not have the time to dive into REST too deeply) and
> simply works against that goal because it makes it look
> as if there was any guarantee that that link will be available.
> There is no such guarantee in REST.
> And try..catch around would not be helpful because it
> would even more emphazise the idea that of failung being
> an *exception*. It is not in REST.

That is API design and is orthogonal to REST itself.

IMHO i think we may be discussing API design and how that may promote
RESTfulness, rather than REST per say (which i think we all have a
fairly good grasp of).

Exceptions can be an effective way of handling failure states (the
Jersey client API already uses such a pattern).

Although as you say there are no guarantees there are good
probabilities that a documented service will not break clients by
removing documented features e.g. a link, of the payment type, MUST be
present in the representation for application/order+xml. Hence there
may be value coding for the probably case and managing errors with

One issue with the current proxy approach is it cannot determine
whether link, of a certain type is present or not, for optional cases,
except via catching exceptions or looking into the representation
headers or entity (no support yet for XPath queries).

A criticism i have of the current proxy approach is that all link
types (actions) are declared, calling some may result in failure
because the state is not valid, and the client needs to know in what
order to call, which is the case anyway regardless of the approach for
machine to machine communication, but splitting up the controller
interface into separate link type interfaces, with transitions method
to other link type interfaces, may better help guide the developer
appropriately through the state machine.

i.e. i think may prefer to see separate proxy interfaces for media
types and link types (the stuff that the client binds to).


> Phew - hope you can figure out from that what I am trying to say.
> Jan
> [1] Let's for now not tackle the question what that means.
> -----------------------------------
> Jan Algermissen, Consultant
> NORD Software Consulting
> Mail:
> Blog:
> Work:
> -----------------------------------
> ---------------------------------------------------------------------
> To unsubscribe, e-mail:
> For additional commands, e-mail: