jsr339-experts@jax-rs-spec.java.net

[jsr339-experts] Re: [jax-rs-spec users] Re: Re: Improving Hypermedia Support

From: Santiago Pericas-Geertsen <Santiago.PericasGeertsen_at_oracle.com>
Date: Tue, 1 Nov 2011 15:17:07 -0400

On Nov 1, 2011, at 2:57 PM, Markus KARG wrote:

> just some ideas…:
>
> * Providing an annotation (e. g. @Transition) at a resource method could mark that method as a transition (i. e. its @Path will be added as a transitional link). That way there is not need to write getTransiational() code at all.

 In an earlier discussion, we (mostly) agree that a pure declarative solutions was _not_ desirable. That, given our understanding of the problem, we should probably let applications write Java code to generate the links.

 This is a safer approach, let's try to focus on an API developers can use without pushing the link generation into the framework. Once we learn more about the problem, we could give the framework more responsibility.

>
> * @Linkable is much more conventient as it induces an automatism to the self URI, what does not necessarily mean that fromResourceMethod is obsolete -- why not give the user *both* possibilities? A complete different idea would be the way we currently implement it in our solutions: Providing a map from entity to "root" URI (what I would not prefer if there would be @Linkable).

 Let me think about this and get back to you.

>
> * I do not understand the problem with the collection. Why not sending just several URIs with the same relation in that case (one for each item of the collection)?

 As link headers? How would you know which one corresponds to which item in the collection? There's no ordering for link headers.

-- Santiago

> From: Santiago Pericas-Geertsen [mailto:Santiago.PericasGeertsen_at_oracle.com]
> Sent: Dienstag, 1. November 2011 19:48
> To: jsr339-experts_at_jax-rs-spec.java.net
> Subject: [jsr339-experts] Re: [jax-rs-spec users] Re: Improving Hypermedia Support
>
> Markus,
>
> Inline.
>
> * In the times of annotation based APIs, the need to implement a method (getTransitional) to provide links more or less looks like an anachronism.
>
> There's no need to implement that method, there is no interface, no annotation. It's just a convention of that sample as stated on the wiki. You can write that code anywhere you want.
>
>
> * There is a separation between resource and entity since the early days of JAX-RS, but the question is since, whether in REST this is natural? In fact, fromResourceMethod("self"), is showing the need to consolidate both as what it actually does *is* mapping resource methods URI paths to entity instances in the end, and it looks rather odd that one has to tell JAX-RS what the URI of the producer actually is (it would be just natural to expect that a RESTful framework knows how to produce a representation of an entity, as it actually is already able to do it... but this is a different discussion and senseless past V1.0 of a spec) Yes, your proposal is aligned to the existing JAX-RS API. But it is not looking smart. I understand that there will be no way to align resource and entity (not for the sake of flexibility, and not for the sake of backwards compatibiity), but, in my opinion it would be better to have some kind of annotation instead of that method. Like @Linkable. From that @Linkable take the value of @Path and you have the "self" URI (and, due to CoC, the root for all other transitions of "this" entity).
>
> Introducing another annotation is certainly a possibility, if it helps.
>
>
> * It looks a bit odd that the client must build the links to the machines manually using a local UriBuilder.
>
> Yes, this is sort of different from the status quo. The idea of using URI templates is because it's the only way to convey this information in the form of link headers when the entity is a collection (one link header, multiple items). Alternatively, we could use links in entities, but as we discussed before, that brings a bunch of other problems. I would rather have applications deal with links in entities (in which case, they may decide not to use link headers at all).
>
>
> It would be more convenient if the client would get the ready-built URIs for all machines instead (either sent by the server, or built by the client's JAX-RS implementation from the received template). I mean, in the human-readable web, people do not see IDs and fiddle them into some form, but the form already has the pre-built links when I click on "Send". So in the machine-readable web, the client application should not have a need to understand that it received a template and guess where to find the IDs to fill in. Or is that templating meant to be an additional feature?
>
> No, it isn't and additional feature. As explained above, it's to provide link information on collections. Of course, this does not prevent the application to provide other links in the entities and follow them in the client; it is just building on the notion of using link headers to guide client bots.
>
> -- Santiago
>
>
>
> From: Santiago Pericas-Geertsen [mailto:Santiago.PericasGeertsen_at_oracle.com]
> Sent: Dienstag, 1. November 2011 18:51
> To: jsr339-experts_at_jax-rs-spec.java.net
> Subject: [jsr339-experts] Improving Hypermedia Support
>
> Hello Expert,
>
> The following wiki page [1] contains some ideas that build on the existing hypermedia support, making it a lot more useful. Please provide feedback.
>
> The server part is based around a new method Link.fromResourceMethod(Class<?>, String). The client part simply provides some minor extensions to take advantage of the extended meta-data. The example uses relative links for convenience; if possible, let's delay the discussion on relative links for a separate e-mail thread.
>
> -- Santiago
>
> [1] http://java.net/projects/jax-rs-spec/pages/HypermediaExample
>