Marc Hadley's Blog

URI Templating

One of the features added to WADL in the latest revision of the specification was the ability to embed parameters in resource path definitions. E.g., the following describes a set of resources identified by a parameterized URI:

<resources base="http://example.com/">
  <resource path="applications/widgets/{widget_id}">
    ...
  </resource>
<resources>

The above extract describes a set of resources identified by the URIs conforming to the following template:

http://example.com/applications/widgets/{widget_id}

Where {widget_id} is replaced by the value of the widget_id parameter when accessing a particular resource.

Defining URIs in this way is useful in a number of scenarios and for the last few months I've been working with Joe Gregorio, Mark Nottingham, David Orchard, James Snell and DeWitt Clinton on a more general specification for parameterized URIs which we are calling URI Templates. The first draft of the specification has now been published as an Internet Draft. To provide feedback on the specification, join the W3C URI mailing list.

URI Templates are deliberately simple; WADL offers a mechanism by which additional metadata can be supplied for a template variable, e.g.:

<resources base="http://example.com/">
  <resource path="applications/widgets/{widget_id}">
    <param name="widget_id" style="plain" type="xsd:int">
      <doc xml:lang="en">
        <xhtml:p>Specifies the identifier of a particular widget.</xhtml:p>
      </doc>
    </param>
    ...
  </resource>
<resources>

When the value of the name attribute of a child param element matches the name of an embedded URI template variable it supplies additional information about that variable. In the above example the XML Schema type of widget_id is xsd;int and some human readable documentation describing the variable is also provided.

The param element also allows specification of a list of possible values (using the option element), default or fixed values, whether a value is required or not, and whether the value is single valued or repeating.

Comments

• Comments from me

  Posted by: brondsem on October 06, 2006 at 03:11 PM

• Hrm, the 'a href' didn't seem to go through. http://brondsema.net/blog/index.php/2006/10/06/uri_structure

  Posted by: brondsem on October 06, 2006 at 03:11 PM

This work is licensed under a Creative Commons License.