users@jax-rs-spec.java.net

[jax-rs-spec users] Re: Feedback on Hypermedia discussion on JAX-RS expert list

From: Santiago Pericas-Geertsen <Santiago.PericasGeertsen_at_oracle.com>
Date: Fri, 11 Nov 2011 13:43:38 -0500

Hi Mattias, Kalle,

 It was nice meeting you at J1, and thanks for the feedback. Inlined

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

 Is this not possible using JAX-RS 2.0 handlers?

> * No link in the example includes consumes media type. Will this be
> included if the resource method is annotated with @Consumes?

 Yes.

> If there
> are multiple media types in consumes/produces, how will this be
> represented?

 Same syntax as HTTP Accept.

> Should it be possible to customize the link verbosity?

 Link.fromResourceMethod() returns a LinkBuilder, so you should be able to customize the link before calling build().

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

 Right.

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

 Sounds interesting, but I think we want to steer clear from the complexity of any type of "path" language in our first attempt at solving this problem.

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

 Is this a major shortcoming?

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

 Ideally, I'd like to see a solution that is annotation free at this stage. However, that may be impractical. I'll explore @Linkable more --others have pointed out shortcomings of @Rel too.

 Thanks.

-- Santiago

> 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