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

From: Markus KARG <>
Date: Mon, 22 Dec 2014 17:29:53 +0100

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 "anybody"
(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

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,

-----Original Message-----
From: Bill Burke []
Sent: Montag, 22. Dezember 2014 16:22
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
>> * 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