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

From: Markus KARG <>
Date: Mon, 22 Dec 2014 23:46:32 +0100

Sorry, typo. I meant "transitional" link.

-----Original Message-----
From: Bill Burke []
Sent: Montag, 22. Dezember 2014 18:26
Subject: Re: Hypermedia API

What is a "transactional" link? I never heard that term before.

On 12/22/2014 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
> 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,
> 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
> 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
> problems outlined by Santiago and Bill, or to outline their own API
> 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

Bill Burke
JBoss, a division of Red Hat