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

From: Santiago Pericas-Geertsen <>
Date: Tue, 15 Nov 2011 18:33:20 -0500


> > 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().
> Well, that would enable explicit programmatic customization, but it wouldn't enable a server default, neither would it allow a client to request a custom verbosity level.

 I have a sense we don't know enough of the problem space to enforce a (standard) default or a (standard) verbosity level. I'm leaning towards letting implementations handle this.
> > 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.
> You're probably right, but I still think you'll need to come up with something else than URI templates for linking to nested items.


> > 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?
> If it's not absolutely necessary I don't think that the API should impose any strict rules on what you choose to handle in a single JAX-RS resource class. There is nothing in the current API that prevents me from doing the above; I should be able to add Hypermedia support to an existing application without any major restructuring.

 I have updated the wiki to discuss @Linkable, but more as an extension of @Rel. Maintaining unique global IDs can be a hassle for large applications, so I'm proposing that to be optional.

> > 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...)
> >
> No comment on this? The key point with the above is that you should be able to add links fluently using ResponseBuilder, e.g.:

 Yes, sure. Once we settle on a strategy we should add convenience methods to facilitate adding links to responses.


-- Santiago

> ResponseBuilder.entity(machine).addLink(getClass(), "self", machine.getId()).addLink(...).build();
> or ("machine.get" is supposed to be the value of the @Linkable annotaion on the self method in the MachineResource class):
> ResponseBuilder.entity(machine).addLink("machine.get", machine.getId()).addLink(...).build();
> This is just for convenience, but I do think it would enable cleaner code than having to build a Link array (there could still be a "links" method that takes a Link array though).
> Regards,
> /Mattias