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

From: Sergey Beryozkin <>
Date: Mon, 15 Dec 2014 10:24:53 +0000

Hi Markus

What I meant is that data model designers may not necessarily need the
help of JAX-RS in order to design the data representations that can
accommodate links.
Example, a data designer wishing for a given piece of data have a link
would add a field such as href, etc... May it is oversimplifying it...
Cheers, Sergey
On 15/12/14 09:46, Markus KARG wrote:
> It is not as simple as you say. You're right that for XML and other generic
> syntax there cannot be a generic entity provider. Hence, a generic XML
> entity provider will not be able to fulfil the application author's wish,
> obviously. But in that case, the request is invalid, as it relies on the
> false assumption that there can be a generic solution with pure XML. XML
> cannot do magic tricks, hence JAX-RS cannot. Certainly the proposed API
> makes only sense for "valid wishes", i. e. the application assembler
> co-bundles entity providers (one or many) which are non-generic, i. e. are
> written according for particular XML schemas (hence not generically
> @Produces("application/xml") but partcularly
> @Produces("application/xml+foobar") for example, where "foobar" is a
> link-aware schema. I understand that for JAX-RS _implementation vendors_
> this looks like a rather seldom case, but from the view of a JAX-RS
> _application vendor_ and _extension vendor_ this is my daily work, actually.
> You're pretty right that this API is only good for the data model designers,
> absolutely. But I am representing these people in this expert group. JAX-RS
> is not only about SPI topics (which are essential for JAX-RS implementation
> vendors) but to a great extend is an API for application vendors. :-)
> -----Original Message-----
> From: Sergey Beryozkin []
> Sent: Sonntag, 14. Dezember 2014 21:30
> To:
> Subject: Re: Hypermedia API
> 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
> Sergey
>> -----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