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

From: Paul Sandoz <Paul.Sandoz_at_Sun.COM>
Date: Wed, 10 Feb 2010 14:26:55 +0100

On Feb 10, 2010, at 1:56 PM, Jan Algermissen wrote:
>> The WADL returned by OPTIONS is dynamically generated and provides
>> more information that what would normally be returned by the Allow
>> header. It is just another representations, of a specific media
>> type, with links in. It is hypermedia and can enable the client to
>> traverse the whole URI space of the application. Think of it as a
>> parallel application exposed by the service.
> From the POV of extending standard HTTP it might make more sense to
> me. Will see.

Yes, it could i think it might depend on what you want to do.
Certainly the WADL generated from JAX-RS resources can make it easier
for the developer to do less work in some respects. But it is not
something we want clients to have to depend on, so we also want to
support hypermedia with links and meta-data in representations etc.

>> The client proxy is using this "parallel application" to
>> dynamically make decisions at runtime.
> Ah, I guess the 'parallel application' is what feels enterrpisey to
> me :-)

REST enterprisey? :-)

Maybe something like WADL can help get better adoption of REST in the

>>> Looking at
>>>> Link: <http://localhost:9998/orders/1/refresh>;op=GET;rel=refresh
>>>> Link: <http://localhost:9998/orders/1/review>;op=POST;rel=review
>>> what worries me is this:
>>> - there is no need for the op parameter because what method to use
>>> will just be part of the definition of 'refresh' or 'review'.
>> It can but the relation needs to bound by the client for processing
>> and it can depend on how the relation is specified. For machine
>> processable clients the op parameter makes this easier. Plus the op
>> parameter could be different depending on the state.
>> For another example consider HTML form hypermedia that can declare
>> the HTTP method to use:
> True. However, the approach influences how people think about link
> relation design. I'd rather have people focus on the business
> aspects than writing link rel specs along the lines of 'rel=pay
> means invoke the pay action on the resource using op=POST'.

But link relationships would have to be generated from those business
aspects *and* also specified as documentation to clients so that they
can bind to them?

And a link relation can be specified as follows:

   The "payment" relation specifies an "op" parameter that is the HTTP
method to use. The op may be one of GET or POST.
   If POST the representation sent in the POST request MUST be of x,
y, z form parameters. If GET the required details
   to make a payment are obtained with a representation Foo.

I believe the above is compatible with how we have currently defined
things in the prototype.

I guess we knew the word "action" would be controversial. As usual
naming things is hard.

> It IMHO obfuscates the broader view on the domain semantics. Maybe
> it is much better to send the order to a payment service... People
> will recognize the implicit object orientation and use it rather
> than stop applying OO to networked systems.

Could be, the application was designed to experiment with the
hypermedia ideas in a particular way and i am sure there are other
ways it could be written (see below).

>>> - the approach emphasizes a specific-API kind of thinking while
>>> in REST we should be thinking in terms of state transfer
>>> "op=POST;rel=review" really just means "tunnel review() through
>>> POST"
>>> - "op=GET;rel=refresh" is not necessary because GET allways means
>>> 'refresh
>>> your current steady state"
>>> I am having trouble to figure out, what the problem actually is
>>> that your
>>> aretrying to solve? I just don't see why all this is necessary or
>>> helpful.
>> The link headers are hypermedia that informs the clients how to
>> make transitions to new application states.
> But the links should inform clients what resources exist and what
> their relation to the current state is. The definition of the rel
> describes the nature of the resource. These semantics include what
> coordination is achieved by certain HTTP requests to that resource.

But is that one particular view of hypermedia?

I do not think the current example violates the principles of

However, i think it would be useful to see another hypermedia example
written along the lines of what you indicate and see if that is
possible with the current server and client prototype (still using
Link headers though just because it is easier).

Our intention for Jersey hypermedia support is not to dictate a
particular hypermedia approach/convention but to provide the means for
the developer to choose from a number of approaches that best suits
their requirements. But this is fiendishly difficult so we have to
start somewhere and build out from that.