[rest-practices] Use of URI templates for query representation

[Mark McLoughlin]

On Tue, 2010-05-25 at 08:30 -0400, Bryan Kearney wrote:
> On 05/24/2010 04:10 PM, Eoghan Glynn wrote:
> >
> > Hi Folks,
> >
> > We've been discussing query representations over on the rhevm-api
> > list[1], coming to the conclusion that a query parameter is the cleanest
> > way of capturing the optionality of a query constraint on a collection-
> > oriented GET.
> >
> > The key point is to avoid leaking detailed knowledge of the URI
> > structure onto the client side, by handing out the URI templates via
> > link headers and/or inline link elements, so that a well-behaved client
> > can treat these as opaque strings.
> >
> > However this opacity is a bit limited in the more widely supported
> > version of the URI template draft, as the client still needs to know the
> > names of both the query parameter and the substitution variable (i.e.
> > "search" and "query" in http://rhevm/vms?search={query}).
> >
> > Interestingly, the latest draft[2] allows a more compact syntax:
> >
> >    http://rhevm/vms{?search}
> >
> > further reducing the client's exposure to the URI structure, by
> > eliminating the named substitution variable. Unfortunately though it's
> > not a reasonable proposition for us to use this latest syntax, as
> > client-side support still seems to be fairly lacking.
> >
> > In fact even the "old" template syntax can be frustrated by the
> > client-side API, for example the JAX-RS UriBuilder doesn't provide a
> > straightforward way of treating the URI template as an opaque string, as
> > it forces the client to parse out the query parameter and substitution
> > variable. For Java clients, the Abdera URI template support seems a
> > superior choice in this regard.
> >
> > In any case if anyone has any strong feelings on the use of URI
> > templates, please shout out.
> >
> > Cheers,
> > Eoghan
> >
> 
> 
> How do you see this working in the client? I tend to not be opposed to 
> hiding the url.. but I am curious how this would look.

One idea we've talked about is to put a limit in advance on the subset
of the URI template spec the server will ever make use of. This would
greatly reduce the complexity on the client side

Cheers,
Mark.