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

From: Markus KARG <>
Date: Wed, 17 Dec 2014 15:34:25 +0100

>> Regarding your summary, you missed what my actual proposal is about: I
>> do _not_ propose that any JAX-RS implementation comes with "MyMBW /
>> pre-bundled or that the existing XML-MBW shall get replaced or enhanced.
> OK, I had missed that yes.

No problem. :-)

>> What I ask for _solely_ is that JAX-RS 2.1 support application
>> programmers and MBW vendors by defining...
>> (A) ...the "@StructuralLink" annotation as a model-independent and
>> MBW-independent way to identify structural links,
>> (B) ...the methods "lookupLink" and "lookupObject" to allow MBWs /
>> MBRs to be able to do the replacements without knowledge of the actual
>> application / resource hierarchy, third party vendors of MBW /
>> MBR (like me) and / or application vendors can build the depicted
>> solution _easier_.
> This seems more useful for framework developers (on top of JAX-RS) than
application developers: I don't think application developers would want to
re-write a MBR/W for XML or JSON.
> This is why I suggested model transformations and interceptors instead.

Again, I did _never_ say anything about MBW in my proposal. The proposal
talks about the existence of @StructuralLink and lookupLink / lookupObject
methods solely. One can use these methods in entity providers _or_
interceptors. Also, there are framework developers out there and I do not
see any reason not to provide supportive APIs for THEM. :-)

> It's also unclear to me that there's enough meta-data to implement those
lookup methods; I believe you would need meta-data connecting models and
resources at least.

Can you please elaborate what you think is missing? Maybe it is simple to
add that missing brick?


-- Santiago

> -----Original Message-----
> From: Santiago Pericas-Geertsen
> []
> Sent: Dienstag, 16. Dezember 2014 19:48
> To:
> Subject: Re: [jax-rs-spec users] Hypermedia API
> Markus,
> Thanks for the example. I don't know if it helped reduced the number
> of questions that I have by much ;) So here they go:
> (1) MyMBW: How does this MBW interact with the existing (or future)
> MBW's for XML and JSON? I would have expected you to use an entity
> interceptor instead to produce another model in which somehow
> references are replaced by URIs in order to pass them to the standard
> MBWs. If you define a MBW instead, I don't know how it plays ball with
> those for JAXB and JSON-B since only one can be active.
> (2) MyMBR: Same comment as for (1). I think you allude to the next
> comment on your e-mail, presumably this reader will know when to map
> URIs to objects based on @StructuralLink, which means that the same
> classes need to be available on the client side for this to work.
> This, in essence, is augmenting the client-server contract; JSON-LD
> solves this by including meta-data in the representation at the
> obvious cost of more verbosity and performance --but frankly that is the
only way.
> To summarize, I can only see this working at the framework level
> (modulo the issue of extending contracts) using interceptors and
> mapping application models before an existing MBW is called and after an
existing MBR returns.
> Likely, application models would need to be "designed" with these
> transformations in mind as well (and we'd need XmlAdapters for JAXB
> and something equivalent for the upcoming JSON-B).
> I may be missing something in your proposal; hopefully others can
> comment as well.
> -- Santiago
> On Dec 16, 2014, at 12:41 PM, Markus KARG <> wrote:
>> Santiago,
>> I hacked a short pseudo code to illustrate what our current solution
>> works
>> like:
>> ---snip---
>> @Path("demo")
>> public class StructuralLinksDemo {
>> public class A {
>> int a_id = 0;
>> @StructuralLink B b_ref;
>> A(int id, B ref) {
>> this.a_id = id;
>> this.b_ref = ref;
>> }
>> }
>> public class B {
>> int b_id;
>> B(int id) {
>> this.b_id = id;
>> }
>> }
>> public class MyMBW implements MessageBodyWriter<A> {
>> @Override
>> public void writeTo(A a, Class<?> type, Type genericType,
>> Annotation[] annotations,
>> MediaType mediaType, MultivaluedMap<String,
>> Object> httpHeaders,
>> OutputStream entityStream) throws
>> WebApplicationException {
>> /*
>> * When rendering instance of 'A' then reference
> 'b_ref' shall get
>> replaced
>> * by '.../demo/b/1' in this demo application!
>> *
>> * As MyMBW is provided by a third party vendor, it
> can neither
>> know
>> * (1) what URI pattern is used in this application
> / resource for
>> 'GET B',
>> * (2) nor whether 'b_ref' actually is intended by
> the application
>> vendor to be a structural link or not,
>> * which can be tricky in case multiple
>> alternative MBW (e. g. JAXB vs. JSON-B) are to be used with
>> * the same data model.
>> * (3) nor what @ApplicationPath or resource's @Path
> are.
>> *
>> * Hence a JAX-RS API is needed which is neutral
> w.r.t to vendor of
>> MyMBW, data format, and
>> * application. This API will...
>> * (1, 3) allow the MBW to 'lookupLink(Object,
> params);', which
>> returns link of ".../demo/b/1"
>> * taken from that resource method in this
>> application which has '_at_GET' and returns 'B'.
>> * (2) allow the MBW to identify those references in
> the model
>> which are to be rewritten without
>> * enforcing MBW-specific annotations in the
>> data model.
>> */
>> Link b_link = JAXRS.lookupLink(a, a.b_ref.b_id); //
> link
>> effectively is ".../demo/b/1" now!
>> // 'b_link' is written to stream instead of 'b_ref',
> e. g. JAXB can
>> be used with custom adapter!
>> }
>> }
>> public class MyMBR implements MessageBodyReader<A> {
>> @Override
>> public A readFrom(Class<A> type, Type genericType,
> Annotation[]
>> annotations,
>> MediaType mediaType, MultivaluedMap<String,
>> String> httpHeaders,
>> InputStream entityStream) throws
>> IOException, WebApplicationException {
>> /*
>> * When parsing document 'A' then URI '.../demo/b/1"
>> has to be replaced by instance of B.
>> *
>> * The problems for MBR are the same as for MBW.
>> *
>> * Hence a JAX-RS API is needed which allows...
>> * (1, 3) to forward URI to JAX-RS for resolution
> without a
>> complete network stack loopback roundtrip
>> * (2) to identify those references in the data
> model which are
>> URIs and shall be replaced by Java object
>> */
>> return new A(JAXRS.lookupObject(b_link)); // returns
> instance of
>> 'B' produced by implicit invocation of 'get_b(1);'
>> }
>> }
>> @GET @Path("a/{a_id}")
>> public A get_a(@PathParam("a_id") int a_id) {
>> // MyMBW replaces instance of B by URI '.../demo/b/1'
>> return new A(a_id, new B(1));
>> }
>> @PUT @Path("a/{a_id}")
>> public void put_a(@PathParam("a_id") int a_id) {
>> // MyMBR replaces URI '.../demo/b/1' by instance of B.
>> ...
>> }
>> @GET @Path("b/{b_id}")
>> public B get_b(@PathParam("b_id") int b_id) {
>> // Client's MBR will invoke 'conditional GET' when replacing
> URI by
>> instance of B.
>> return new B(b_id);
>> }
>> @PUT @Path("b/{b_id}")
>> public void put_b(@PathParam("b_id") int b_id) {
>> // Client's MBW will invoke 'conditional PUT' when replacing
>> instance of B by URI.
>> ...
>> }
>> }
>> ---snip---
>> I think the comments expain pretty well how it works. Our particular
>> MyMBW / MyMBR utilizes JAXB's XmlAdapter to exchange objects with
>> URIs and vice versa, and it works on both, client and server side.
>> But as I
> said before:
>> It is our particular data format, so it is _not_ a generic XML
>> solution, as we must know how the syntax for links is like. Anyways,
>> it pretty well depicts the demand on behalf of a structural links API.
>> What the API cannot do is -unfortunately- simplify client programming:
>> Unless JAX-RS makes WADL discovery mandatory, the client cannot know
>> the URI patterns needed. So the proposal is a first step for server
>> side
> only.
>> I assume that Casey's solution works similar and would benefit from
>> the proposed annotation and lookupLink / lookupObject methods in the
>> same
> way.
>> If there are questions, just ask. :-)
>> Regards
>> -Markus
>> -----Original Message-----
>> From: Santiago Pericas-Geertsen
>> []
>> Sent: Montag, 15. Dezember 2014 16:14
>> To:
>> Subject: Re: Hypermedia API
>> Markus,
>> I have a lot of questions about the proposal, but I feel most can be
>> answered if you translate your ideas into a sample application.
>> Assuming what you're proposing is available in JAX-RS, how would your
>> application look like? Could you provide a sample app?
>> -- Santiago
>> On Dec 15, 2014, at 7:38 AM, Markus KARG <> wrote:
>>> Sergey,
>>> yes and exactly at that point we'd like to give the data model
>>> designer an annotation at hand which marks that field as an
>>> injection point for the actual URI at runtime. That's the sole idea
>>> of the proposed API. :-)
>>> Regards
>>> -Markus
>>> -----Original Message-----
>>> From: Sergey Beryozkin []
>>> Sent: Montag, 15. Dezember 2014 11:25
>>> To:
>>> Subject: Re: Hypermedia API
>>> 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
>>>> 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
>>>>> 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