Home > REST Service vs. Non-REST Service Contracts > URI Templates and Resource Queries

URI Templates and Resource Queries

Resources that capture the result of specific queries can pose a problem for conventional hypermedia. Service consumers that receive a hyperlinked resource identifier at runtime for which they want to perform an ad-hoc query will often need a way to figure out the necessary query parameters.

For example, a service consumer may receive the resource identifier http://invoice/reports/ for a resource that provides invoice reporting functionality. All the service consumer has at hand is the base URL, plus knowledge of what it wants to query. What it does not have knowledge of is the syntax required to append the query parameters to the http://invoice/reports/ resource in a manner that will be understood by the resource.

A URI template establishes the structure of a URI by indicating what additional values can be added (and what these values represent). A sample URI template for the aforementioned resource could be:

http://invoice/reports/{year}/{month}

So, what the service consumer needs is this template in order to assemble the resource identifier according to the resource's pre-defined requirements. The template could be hard-coded into the service consumer logic, but this would undermine the loose coupling benefit of hypermedia we discussed earlier.

To address this particular situation, there are two common techniques:

  1. Have a service designated to provide URI templates at runtime. This way, upon receiving the base URI, the service consumer can further request and retrieve its corresponding template at runtime.
  2. Standardize query-related parts of URIs across all REST services within a given service inventory. This way, the service consumer can contain hard-coded logic enabling it to assemble the query statement on its own. The service consumer will then end up being coupled to a standardized resource identifier structure, as opposed to a structure specific to the Invoice service.

These techniques can also be applied for other forms of parameter-driven resource interaction.