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

[jsr339-experts] Re: Improving Hypermedia Support

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

Santiago,

 

just some comments which came into my mind almost instantly:

 

* In the times of annotation based APIs, the need to implement a method
(getTransitional) to provide links more or less looks like an anachronism. I
have no proposal at hand, but I think these days people would love to find
annotations instead, marking some kind of Link builder method.

 

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

 

* It looks a bit odd that the client must build the links to the machines
manually using a local UriBuilder. 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?

 

Regards

Markus

 

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