[jax-rs-spec users] Re: Hypermedia API

From: Markus KARG <>
Date: Tue, 23 Dec 2014 00:04:51 +0100


about "not wanting": Good to hear that Oracle will second this. I got the
impression that structural links support is not wanted as only Bill
responded to this essential question directly -- and he clearly said "no"
two times. For me this currently looks like "possibly go" from Oracle, "no
go" from Red Hat, and "no answer" from Apache and others hence my
wakeup-call to all experts. It makes no sense to provide an API that will
not be supported by Red Hat IMHO, as sad as sounds for "real" RESTafarians.

About the proposal: It seems that was a misunderstanding out of the
situation where I discussed similarities of my solution with Casey's just
for couriosity whether he found a general solution while we didn't. I
thought I made clear several times that we do not have a _generic_ solution
but that we are currently hand-coding static URLs (like Bill prefers to do)
and I'd just proposed that JAX-RS 2.1 provides an API to get rid of that
need. Maybe it was not clear enough that the posted pseudo-code was just
intended as an outline of the core idea how the API (not the implementation)
_could_ look like. In fact our real solution does _not_ look like that, as
it uses hard-coded URLs. It is _not_ a framework we can use as a template
for JAX-RS 2.1 due to that reason, but it is an existing implementation we
want to get _rid off_ in favor of a possible future JAX-RS 2.1 feature. I
hope I was unambiguous this time.

So how to go on from here? Anybody solutions at hand for the problems
discovered by Santiago and Bill, or possibly a better API (not
implementation) design? :-)

BTW, I think it would be great to get some "go" or "no go" w.r.t to the idea
of standadizing a structural links API from those experts who had not yet
commented on this topic. While I am convinced that structural links will
play a bigger role in future once such an API is there, I certainly cannot
forecast the future, hence it would be nice to hear more opinions.


-----Original Message-----
From: Santiago Pericas-Geertsen []

Sent: Montag, 22. Dezember 2014 18:34
Subject: Re: Hypermedia API


 I think we all want to provide tools for people to write better
applications, including better support for structural links, if possible. If
we didn't, we wouldn't have spent time evaluating your proposal.

 So this is not about wanting to support something, as you are trying to put
it for some reason, it is about finding a solution that we think is
reasonable in terms of what it provides for developers and what it demands
from the spec and the implementors. You seemed to suggest you had such a
solution, and that's how we got here.

-- Santiago

> On Dec 22, 2014, at 11:29 AM, Markus KARG <> wrote:
> Santiago and Bill,
> I think we're completely running in the wrong direction! I never
> demanded that JAX-RS 2.1 must have support for structural links.
> Actually this discussion started by an introduction of mine which
> clearly said that _structural_ links are NOT the most important issue
> with hypermedia, while improved support for _transactional_ links
> indeed IS. Indeed it was Santiago who ASKED for a proposal how such an
> API COULD look like, basing on the manually hard-coded solution we've
> developed in the past and run in-field for years. I never said my
> proposal is either complete or fully working, but CLEARLY said it is
> just a first hacked _draft_ which COULD serve as a base for a
> solution. It is definitively NOT the final solution itself and won't
> become it if nobody wants such an API or is willing to provide answers to
the questions you raised.
> Instead, I asked TWICE if we actually WANT structural links support,
> and did not get an answer from anybody but Bill so far.
> Hence, I will stop here discussing any details on my proposal as it
> was never mentioned as "the" final solution, nor seems to be wanted by
> (I wonder why Red Hat, Casey and me ever invested time to provide such
> solutions). If the JSR 370's "hypermedia" charter is to be interpreted
> as "transaction links only" this is fine for me.
> I would be happy if JAX-RS 2.1 comes up with a vendor-neutral
> structural links support API, but I can live more years without it. I
> do not have a general solution in my pocket, and I never pretended so.
> If such an API is wanted, I hereby ask the other experts to chime in
> and find solutions to the problems outlined by Santiago and Bill, or
> to outline their own API proposal instead.
> It's not only _my_ job to make up my mind about an API and solve all
> problems alone. This is a common effort. Either you help with this, or
> we simply kill the topic right now, as apparently nobody has interest
> in providing a solution.
> Merry X-mas,
> -Markus
> -----Original Message-----
> From: Bill Burke []
> Sent: Montag, 22. Dezember 2014 16:22
> To:
> Subject: Re: Hypermedia API
> On 12/22/2014 10:01 AM, Santiago Pericas-Geertsen wrote:
>>> On Dec 21, 2014, at 1:10 PM, Markus KARG <
>>> <>> wrote:
>>>>> About the missing metadata can you please elaborate what you think
>>>>> is missing hence imposes a need to "guess"?
>>>> The container has to guess how to resolve B in your example because
>>>> you have not provided the resource class and method name that
>>>> contains the @Path that resolves B.
>>> Maybe I miss something, but I think it should be fairly
>>> straightforward to implement "lookupLink" given an instance of class
>>> "B" at runtime using a dumb brute force algorithm:
>>> * Iterate over all resources
>>> * For each resource iterate over all resource methods
>>> * If resource method's return type is "B", add it to candidates list.
>>> * After that, iterate over all candidates
>>> * If candidate is "@GET" then return this one as the final result.
>>> * If no candidate is "@GET" then return the first one as the final
> result.
>>> * If there are no candidates, then this application has a
>>> programming error, because the application vendor wants to link "B"
>>> but has no resource method for it.
>> Did you even work out an example for this algorithm? I see several
>> things wrong with it: (1) the fact that a resource method returns a
>> certain type, does not imply is the one you want (2) path variables
>> (3) resource locators, etc.
>> Example (1):
>> @Path("/address/{id}")
>> class AddressR {
>> @GET
>> public Address get(@PathVariable("id") String id) { ... } }
>> @Path("/person/{id}")
>> class PersonR {
>> @GET
>> public Person get(@PathVariable("id") String id) { ... }
>> @GET
>> @Path("address")
>> public Address getA(@PathVariable("id") String id) { ... } }
>> @Path("/company/{id}")
>> class CompanyR {
>> @GET
>> public Company get(@PathVariable("id") String id) { ... }
>> @GET
>> @Path("address")
>> public Address getA(@PathVariable("id") String id) { ... } }
>> There are 3 resource methods returning Address, but which one do you
>> choose? It depends. Also, how does the framework fill out the values
>> for {id} in each case when constructing a URI?
>> This does not even consider the issues related to resource locators
>> whose return types are other resources and not model types.
>> Is it possible to solve this problem by providing additional
>> meta-data (e.g. annotations)? Perhaps, but I don't know if we want to
>> go
> that far ...
> I see we are thinking the same Santiago. This is the problem I've had
> so far with any annotation-driven hypermedia extension (even our own).
> * How do you resolve the resource method to fill the link?
> * How do you fill in the path, query, and matrix params of the link?
> * How do you decide the title and rel of the link?
> * How do you deal with standard and custom link types? "self",
> "edit", "delete", "update", etc...
> IMO, too much magic here, IMO, it would just be simpler to do it manually.
> --
> Bill Burke
> JBoss, a division of Red Hat