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

From: Sergey Beryozkin <>
Date: Sun, 14 Dec 2014 20:29:49 +0000

Hi Markus
On 12/12/14 18:34, Markus KARG wrote:
> This is correct, hence it is impossible to have a generic solution, but need
> support by Entity Providers. As Entitiy Providers are aware of the abilitiy
> how to merge structural links, they -and only they- can decide about the
> sole correct way to add them at time of coding and how to resolve them at
> time of decoding.
The above is a conflicting statement. A solution involving the entity
providers can not qualify as a generic solution because the providers
have no idea about the schema constraints possibly applied to a
representation to be produced from a given bean.
This solution can work in some cases where no schemas are involved or a
consumer does not care about the validation or when schemas are designed
to allow the extra content. But it is not a generic solution.
To be honest I do not expect such solutions to become mainstream.

It is really about people designing the data model, the one meant for
the external consumption, with the links in mind, auto-augmenting the
existing data can be interesting but does not appear to be something 2.1
should be spending much time on


> -----Original Message-----
> From: Sergey Beryozkin []
> Sent: Donnerstag, 11. Dezember 2014 22:24
> To:
> Subject: Re: Hypermedia API
> The problem with auto-augmenting XML with links is that it can produce
> non valid XML, schema - invalid. A corresponding schema instance (and
> for most serious applications there will be a schema) may not be open
> enough for a given XML instance to include extra attributes or elements
> representing the links.
> Sorry if I misunderstood
> Sergey
> On 11/12/14 21:02, Markus KARG wrote:
>> I do not see how JSON-LD is any better than XML based links, as it
>> doesn't solve the root problem: In the end it plays no role whether the
>> document syntax is JSON or XML. The problem is the missing API. To make
>> structural links work, there must be standard annotations in the entity
>> POJOs, and the entity providers must process them, and the spec must
>> unambiguously tell how. Yes this is tough, but I think that shouldn't be
>> an excuse for not standardizing it. Rather we should concentrate on the
>> question whether we _want_ standardize structural links or not, and in
>> case we do, who provides the RI for that, as possibly Casey has
>> something which can be built upon, and implementing it won't be cheap,
>> and it has to be done by _all_ JAX-RS vendors.
>> So my question to the spec leads and vendors is: Shall we really go on
>> with discussing structural links, or is it simply out of scope of JSR
>> 370? Frankly, I would love to have structural links API, but I certainly
>> respect it if none of the vendors wants to pay that. In the end, a
>> standardization should standardize existing products, not enforce _all_
>> vendors to build something made up synthetically from scratch.
>> *From:*Santiago Pericas-Geertsen
>> []
>> *Sent:* Donnerstag, 11. Dezember 2014 20:47
>> *To:*
>> *Subject:* Re: Hypermedia API
>> Casey,
>> Yes, structural links in entities is not something that JAX-RS
>> provides any "special" support for (in some cases, people have included
>> them in headers, but it is arguably less clean).
>> The reason why JAX-RS hasn't done much (other than the JAXB Link
>> serialization bit) is that JAX-RS has not been, and likely never will
>> be, in the business of (structured) entity serialization; it delegates
>> to specific JSON and XML libraries for that. Clearly this is an issue
>> for link processing, but the architectural decision of not duplicating
>> existing APIs is certainly sound.
>> As you point out, JAX-RS would need some additional meta-data to
>> "learn" about these links in representations. However, this needs to be
>> done without introducing unnecessary coupling and in a standard manner
>> --that is, not in a way that would require using a JAX-RS implementation
>> for it to work. This is a difficult problem to solve.
>> JSON-LD [1] is a step in the right direction, especially since
>> becoming a W3C recommendation. Not having full control of the
>> serialization is still an issue for us, but perhaps there's something we
>> can do working with the new JSON-B EG.
>> -- Santiago
>> [1]
>> On Dec 11, 2014, at 1:43 PM, Casey Lee <
>> <>> wrote:
>> 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.
>> -Casey
>> On Wed, Dec 10, 2014 at 1:36 PM, Markus KARG <
>> <>> wrote:
>> Santiago,
>> you asked for statements on the field of hypermedia and reactive. I will
>> take the chance to start discussion hereby on the field of hypermedia and
>> provide a starter for reactive in a separate thread.
>> Some weeks back I gave a lecture on JAX-RS 2.0 big picture at JUG
> Stuttgart,
>> just as I did infrequently at other events before. I'd like to describe
> the
>> reactions as those were stereotypical, independent of audience, location
> and
>> date. People where convinced by the very clean separation of concerns
>> (application made up from pure domain objects, technical aspects separated
>> from domain model), and the mostly declarative programming style (simply
>> adding annotations to declare needs, engine solves the needs "under the
>> hood" using a sophisticated and extensible technical infrastructure). But
>> when the presentation came to hypermedia support, they were some kind of
>> shocked by the mostly algorithmic coding style needed to make it work,
>> voiding the aforementioned separation of concerns and declarative code
>> style. While the existing API clearly is a foundation to achieve at least
>> "something", real HATEOAS becomes a hack with the existing low level
> support
>> only. Code gets cluttered with old-style techno-punk, which is hard to
> read
>> and understand. This is due to the lack of a declarative way to tell the
>> infrastructure how to make up the links from application domain state, and
>> how to provide the links to an entitiy provider so he can merge them into
>> the wire-level representation. Certainly everbody would vote for a
>> declarative kind of solution fitting into the existing infrastructure. On
>> the other hand, nobody (yes, really zero) people wanted to agree that they
>> have a REAL NEED for HATEOAS (hence, neither for an explicit HATEOAS API)
> as
>> 100% of all attendees admitted that their recent and current RESTful
>> projects are on level 1 or 2 of the REST Maturity Model only, and that the
>> largest obstacle to level 3 is not a techical issue (hence not a missing
>> explicit HATEOAS API) but the fact that HATEOS as a paradigm simply is not
>> well understood by most of them and / or they do not see the actual
> benefit
>> of HATEOAS in the real world: It wouldn't pay off, but it would be cool,
> to
>> sum it up.
>> So the question is: Is HATEOAS commonly understood well enough that it
> makes
>> actual sense to provide an explicit API for it, or does it make sense to
>> make an API even when it is not? And if we define an API, do we all agree
>> that it should support the separation of concerns and declarative style
> that
>> is typical for JAX-RS?
>> I think without an agreement on that general topics, it wouldn't be a good
>> idea to discuss any kind of details of API proposals in the area of
>> Bill and Sergey, what's your opinion on that?
>> Regards
>> -Markus
>> -----Original Message-----
>> From: Santiago Pericas-Geertsen
> []
>> Sent: Mittwoch, 10. Dezember 2014 20:03
>> To:
>> <>
>> Cc: Marek Potociar
>> Subject: Welcome to the JAX-RS 2.1 EG
>> Hello Experts,
>> Welcome to the JAX-RS 2.1 (JSR 370) expert group!
>> This is the official mailing list for the JSR. Note that the old mailing
>> list for JAX-RS 2.0 (JSR 339) is still available for 2.0 matters.
>> Before we start any discussions, I would like everyone to take a couple of
>> minutes and read the JSR description one more time to make sure we are all
>> on the same page ;)
>> ===
>> 2.1 Please describe the proposed Specification:
>> Server-Sent Events (SSE) is a new technology defined as part of the HTML5
>> set of recommendations for a client (e.g., a browser) to automatically get
>> updates from a server via HTTP. It is commonly employed for one-way
>> streaming data transmissions in which a server updates a client
> periodically
>> or every time an event takes place.
>> JAX-RS 2.0 introduced the notion of asynchronous processing for both the
>> client and the server APIs. However, asynchronous processing alone cannot
>> deliver on all the promises of a modern architecture without the help of
>> non-blocking I/O. If only blocking I/O is available, asynchronous
> processing
>> simply pushes the problem from one thread to the next --this is akin to
>> borrowing from a person to pay another, the problem is not really solved,
>> only deferred. Thus, support for non-blocking I/O is necessary to achieve
>> high throughput and efficiently manage resources like threads.
>> In summary, the following is a list of the tasks in scope for JAX-RS 2.1:
>> * Adding support for SSE.
>> * Improving integration with CDI.
>> * Exploring support for non-blocking I/O in providers (filters,
>> interceptors, etc.).
>> * Evaluating ways in which declarative security can be supported either
>> directly in this JSR or by leveraging other EE-platform JSRs.
>> * Making JAXB conditional on runtimes where it is available.
>> * Providing integration with JSON-B.
>> * Building upon the hypermedia API added in version 2.0.
>> * Investigating the reactive programming paradigm as a way to improve the
>> JAX-RS asynchronous client API.
>> * Evaluating any requirements necessary to support the use of JAX-RS
>> resource classes as controllers in the MVC 1.0 JSR.
>> ===
>> Some useful links:
>> [JSR]
>> [JAX-RS Spec] [JIRA for 2.1]
>> [RI]
>> [E-mail Archives]
>> As before, all of our discussions will be conducted using the expert's
>> alias and (automatically) CCed to the user's alias.
>> Some of the 2.1 tasks above require coordination with other specifications
>> (JSON-B, Security), so these tasks will tackled later on in the process.
>> We have tentatively selected 2 topics to start our discussions, both of
>> which require some investigation, these are: hypermedia improvements and
>> reactive programming. If you have any suggestions/comments/concerns about
>> these two topics, feel free to start a discussion about them. We will be
>> sending some more info as well in the upcoming weeks.
>> Looking forward to working with all of you!
>> --
>> Santiago Pericas-Geertsen
>> Marek Potociar
>> JSR 370 Spec Leads