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

From: Markus KARG <>
Date: Thu, 11 Dec 2014 21:39:15 +0100


while I actually expect that declarative support for transitional links (HATEOAS) is the more urgent need from the view of REST, I though am curious about the annotations you defined for structural links: How do you technically resolve them? Did you write your own message body writer? We simply used JAXB's Adapters to solve this task, but that's only working with JAXB obviously. Will your solution work with *any* kind of context and entities or is it tightly coupled with your particular application?


-----Original Message-----
From: Casey Lee []
Sent: Donnerstag, 11. Dezember 2014 19:43
Subject: Re: Hypermedia API

I agree, Markus that the issue here is the technical infrastructure (or lack of) around HATEOAS has limited its adoption and understanding. Specifically, the limitation is with the fact that the links we currently have with JAX-RS 2.0 are only transitional links in the HTTP header, but no support for structural links in the Entity.

I feel the issue is that the current API is all about RESOURCES, which causes server side developers to focus more on the URIs than on the REPRESENTATIONS. Additionally, this has leaked into the client API, causing the client side developer to also have an awareness of the resources, which limits the need to think about links or at best makes the links optional.

Is there an opportunity to evolve the API to enable adding (server
side) and retrieving (client side) Links from the Entity? One approach would be by annotating your Entity POJOs where Links would be added. This would allow some declaration of the structural (and possibly transitional) links for the representation.

This would cause developers (client and server side) to begin to think about links and the structure/relationships of the representations.

At our organization, we've developed our own sets of annotations for declaring the structure of your representations and associating them to a media type. All of our documentation and the API that the client uses is based on the following:

* Follow a link
* Get back a representation
* Find a link in the entity
* Repeat

This causes us to spend most of our effort describing the media types, and very little if any effort describing the URIs.