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

From: Markus KARG <>
Date: Sun, 14 Dec 2014 09:25:01 +0100

Nobody wants to make up anything from scratch here.

As mentioned earlier in this discussion, it indeed started _because_ there are existing solutions (at least my own and Casey's), but we both use properietary ways to work around the limitations of the JAX-RS 2.0 Entity Provider API currently, and we both would be happy if a future JAX-RS 2.1 application author could model against one common and vendor-agnostic API _instead_. Also it was already mentioned that indeed the most-interesting actual implementations will typically use a widely spread (or anticipated widely spread) standard like XML and / or JSON-LD. So I'm unclear what concern you actually aim at. Can you please elaborate so we can try to dispel?

If your fear is introducing new features into your particular JAX-RS implementation, then you can stay relaxed. We only want to extend JAX-RS to the extend that it provides an API binding application vendors and entity provider vendors together, but nobody wants to enforce JAX-RS products to provide particular entity providers if not already existing. Instead, it opens a market for independent vendors of such providers (like possibly me). Certainly it would be pretty fine if JAX-RS implementation come pre-bundled with such entity providers for XML or JSON-LD, but I do not see a need to enforce this by the JAX-RS specification.


-----Original Message-----
From: Bill Burke []
Sent: Sonntag, 14. Dezember 2014 01:51
Subject: Re: Hypermedia API

Sounds great, as long as you are modeling it against existing solutions.
  I'm pretty sure there are a few out there. If you're just making it up from scratch -1 for me here.

On 12/13/2014 1:03 PM, Markus KARG wrote:
> While I agree that certainly XML and JSON should be supported out of
> the box, the API itself must be representation agnostic. Hence the
> idea for annotations interpreted by entity providers without naming
> any particular media type. :-)
> -----Original Message-----
> From: Bill Burke []
> Sent: Samstag, 13. Dezember 2014 15:16
> To:
> Subject: Re: Hypermedia API
> I'd like any hypermedia API to be modeled against existing solutions rather than to create one from scratch. XML and JSON pretty much cover the vast majority of representations that are used by REST implementations, so integration with those media types would be preferable.
> On 12/12/2014 5:04 PM, Markus KARG wrote:
>> Actually I do not share this judgement of the situation. I think that it would be a valuable addition to JAX-RS to cover the area of representation a bit deeper by providing an API for structural links. The question is more about whether the vendors would second that. About developers, my opinion is: "Build it an they will come!".
>> -----Original Message-----
>> From: Casey Lee []
>> Sent: Freitag, 12. Dezember 2014 17:17
>> To:
>> Subject: Re: Hypermedia API
>> Our implementation is accomplished in a custom MessageBodyWriter that is aware of the annotations. I agree that trying to pull this up in the API would be very challenging for the vendors, and likely complex for developers to use.
>> After further consideration, I think that there is too much of an
>> impedance mismatch between the strategy of JAX-RS API and this type
>> of approach. In order to standardize structural links you need to
>> get into the business of the representations, however JAX-RS is only
>> focused on resources not on representations. In hindsight, I think a
>> greater focus on representations over resources may have yielded an
>> API that encouraged more HATEOAS knowledge and implementation. The
>> focus on resources in JAX-RS API (and others like Spring MVC, Play,
>> etc) have led developers to think resource first. At the end of the day, what you have is server side developers having to communicate resource information (URIs) out of band to the client side developer.
>> This has led to projects like Swagger (which I love BTW) that focus on documentation of resources.
>> What is the alternative? If the focus was on representations, then you'd have server side developers communicating the details of the media types, which include which link rels are available within the structure of the media type. No more need to communicate URIs, other than a "home" resource. Alas, I think it may be too late to make a major shift like this with the API...and adding it to the API would just add confusion for the developers.
>> In conclusion, I think not only would it be expensive for vendors, but it would also be confusing for developers given the current momentum around resources.
>> -Casey
>> On Thu, Dec 11, 2014 at 1:02 PM, 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 HATEOAS.
>>> 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
> --
> Bill Burke
> JBoss, a division of Red Hat

Bill Burke
JBoss, a division of Red Hat