We have been following the discussion on Hypermedia support on the
expert list, and have a couple of comments to the example on the wiki
(
http://java.net/projects/jax-rs-spec/pages/HypermediaExample).
Link Header
-----------
* Headers are harder to work with than having the links in the actual
response body, e.g. from javascript. It might be possible to provide
the ability to customize link representation using e.g. a
MessageEnricher annotated with @Provider, which will give you access to
headers and entity before MessageBodyWriter is invoked. This opens up
for having the links in the message body if that is what you want. A
client counterpart for MessageEnricher might be needed.
* No link in the example includes consumes media type. Will this be
included if the resource method is annotated with @Consumes? If there
are multiple media types in consumes/produces, how will this be
represented? Should it be possible to customize the link verbosity?
* Nested items are really tricky. The use of URI templates in links for
nested items feels a bit shaky. The rel attribute for nested items in
the header is 'item', but in reality this should be a self link for the
respective item. This could be a convention, but what if your
representation contains multiple nested lists or objects? Maybe this
type of link could also have a 'path' attribute, pointing to the
collection/position that it relates to (e.g. in XPath, JSONPath or a
custom path format). This would work with the URI templates, but it
also opens up for serving absolute links to nested elements without
using a template.
Link/LinkBuilder
----------------
* Use of an @Rel annotation makes it impossible to handle different
resources in same class, e.g. machines and machine (if we need a 'self'
rel for both of these). This would be solved by a global @Linkable
annotation (with id and rel attributes), which would also make the Link
construction less verbose:
Link.from(linkableId).build(params)
* It would still be possible to allow the class/method convention if
that is desired (as in your example).
Link.fromResourceMethod(someClass, someRel).build(params)
ResponseBuilder
---------------
It would be nice to be able to append links directly in the
ResponseBuilder, e.g.:
ResponseBuilder.addLink(LinkableId, params...)
ResponseBuilder.addLink(ResourceClass.class, rel, params...)
ResponseBuilder.addLink(Link.fromResourceMethod(...).build())
ResponseBuilder.links(Link...)
Best Regards,
Mattias Hellborg Arthursson and Kalle Stenflo
Jayway