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

From: Markus KARG <>
Date: Fri, 12 Dec 2014 19:34:40 +0100

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.

-----Original Message-----
From: Sergey Beryozkin []
Sent: Donnerstag, 11. Dezember 2014 22:24
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

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
> just as I did infrequently at other events before. I'd like to describe
> reactions as those were stereotypical, independent of audience, location
> 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
> only. Code gets cluttered with old-style techno-punk, which is hard to
> 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)
> 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
> of HATEOAS in the real world: It wouldn't pay off, but it would be cool,
> sum it up.
> So the question is: Is HATEOAS commonly understood well enough that it
> 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
> 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
> 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
> 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