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

[Eoghan Glynn]

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


[1] https://fedorahosted.org/pipermail/rhevm-api/2010-May/000213.html
[2] http://tools.ietf.org/html/draft-gregorio-uritemplate-04