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

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

From: Markus KARG <markus_at_headcrashing.eu>
Date: Tue, 1 Nov 2011 19:57:44 +0100

Santiago,

 

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.

 

* @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).

 

* 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)?

 

Regards

Markus

 

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