On Feb 10, 2010, at 12:34 PM, Jan Algermissen wrote:
> Hi Paul,
>
> On Feb 10, 2010, at 11:45 AM, Paul Sandoz wrote:
>
>> [...]
>
>> And one area of definite controversy is the client proxy will
>> utilize WADL, dynamically via OPTIONS, to obtain additional meta-
>> data e.g. to know if a name corresponds say to a query parameter or
>> say a form parameter. As i said this is experimental :-)
>
> I think WADL can maybe be a good tool for server side code
> generation but exposing WADL to the client violates the hypermedia
> constraint and should be discouraged. (Paraphrasing Roy) all of
> REST's descriptive effort should be spent in media type and link
> relation specifications.
The WADL exposed by Jersey in no way violates the REST constraints. A
violation will only happen if the client uses it the wrong way (for
example statically generating code for resource types), which is true
of any hypermedia exposed by a service.
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.
The client proxy is using this "parallel application" to dynamically
make decisions at runtime.
>
> 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:
http://www.w3.org/TR/html401/interact/forms.html#adef-method
> - 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.
The server-side plugin (a server-side filter in this respect) provides
support for adding link headers and validating state transitions.
If we actually documented the link relationships one could implement
an appropriate client side to operate on those link relationships for
a fully compatible hypermedia application.
The way Santiago has currently done this is to define a client
interface declaring the link relationships (which always need to be
bound to in REST) and then the proxy leverages WADL so that the
developer does not have to write as much code.
Paul.