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

From: Paul Sandoz <Paul.Sandoz_at_Sun.COM>
Date: Wed, 10 Feb 2010 13:07:00 +0100

On Feb 10, 2010, at 12:00 PM, Jan Algermissen wrote:

> [follow up]
> I think there are different issues that need to be discussed
> separately:
> 1) What is the best way for a framework to support the
> server side developer in the task of adding links to
> the served representations?
> In my experience it is often hard to separate the
> creation of a domain object's representation from
> the addition of links in order to adhere to good
> programming practice. Usually I eventually have
> to copy/paste some code (which I hate).
> In part this is a result from links being part
> of the representations and sometimes also
> being placed in headers.
> Framework support tp ease thsese issues would be
> a good thing. But it would be purely server-side.

Yes. We have found that Link headers are rather practical in a number
of cases, but we really started using them first because it was easier
to implement to start experimenting :-)

> 2) What is the proper way to design media types and
> links?
> I really (strongly) think that a framework should
> either know exactly what it is doing or be silent
> about this matter altogether.
> Since the whole issue of machine2machine media types
> is still not thoroughly analysed (IMHO) it is very
> dangerous to promote a certain approch (re 'action
> resources').
> This is what caused my worries yesterday. Especially
> since I think that the proposed approach misses the
> point comletely.

This is research :-) which is always risky, but even in failure good
lessons will be learned. You have to start somewhere with
experimentation. So i am not sure you need to think of this as
"dangerous", although the way i interpret that is you really care
about this area and are extremely interested in seeing a good outcome.

I prefer to think of it as an exciting exploration that we are just
starting out on :-)

What IMHO would be dangerous and very irresponsible is premature

> 3) What is the proper way to implement a RESTful client?
> This is in my opinion also not yet solved at all and
> most approaches just introduce coupling between client
> and server that REST aims to avoid.
> As with 2) a framework should know exactly what it is
> doing in order not to foster the proliferation of
> unRESTful REST systems.
> I am very concerned about this because I consider REST
> done wrong to be worse then RPC done right. Mostly so
> because unRESTful REST tends to introduce coupling that
> is completely undocumented while with RPC we at least
> have IDL class definitions. (Yes, I know this from
> personal wrong doing (shame on me) :-)
> Putting something like in the client code
> violates RESTs hypermedia constraint because it hard
> codes an assumption that REST does not support. In REST
> there is no way to know at design time whether there
> will be a 'pay' traversal froom the 'order'-state at all.
> The right way to code the client here is to follow the pay
> traversal *if* the steady state reached after a GET on
> the order resource provides the necessary transition.

It you take a look at the proxy implementation it is indeed doing
something like that (as presented in the logged output). Internally
states will be checked based on the link relationships in the
representation. Although i think the error handling could be better.

We decided that for a machine to machine approach exposing the link
relationships as an interface can be useful both for development and
tooling and i do not think it has to violate the REST hypermedia
constraint for it to work.

As long as the proxy does the right thing working correctly or
throwing exception to react to unexpected cases i think it is just a
slightly different programming model to what one might expect.

> If it doesn't, the client must still handle the situation
> (probably by trying something else, probably by logging
> an error for human reaction).
> Hiding this issue wil lead client side developers to
> wrong assumptions about the nature of the architecture.

> Too many people are doing this already and I think Jersey/
> JSR 311 should work against that trend instead of making
> it worse.
> Having said all that - naturaly I have my own understanding
> how it should work and I am happy to add this to the debate.
> (Will be about one or two weeks before I can post that)