Marc Hadley's Blog

June 2006 Archives

WADL Enhancements

In this entry I describe some of the language enhancements that will be in the next version of the WADL specification. These enhancements are the result of feedback I've received from other folks using the language and experience gained implementing a Java processor for WADL.

Resource References

Currently you can define a method or representation in one place and then include that definition by reference elsewhere. This is useful if the same representation is used in multiple method definitions or if the same method applies to more than one resource. Extending this capability to the resource element allows a common resource hierarchy to be re-used in multiple places. E.g.:

<application>

  <resources base="http://example.com/">
    <resource href="stock">
      <resource href="#widgets"/>
    </resource>
    <resource href="order">
      <resource href="#widgets"/>
    </resource>
  </resources>

  <resource id="widgets" path="widgets">
    ...
  </resource>

</application>

Identification of Links

Whilst it would be possible at runtime to compare a URI embedded in a representation with the URIs of all of the resources in a WADL description to identify which resource it identifies, it would be preferable to be able to specify the resource targeted by a link up front where that information is known.

This is achieved in WADL by adding a new element to the language: link. The link element is a child of the existing representation_variable element and is used to indicate that the value of a representation component is a link to a described resource. The link element is syntactically similar to the HTML link element but differs semantically in that its href attribute identifies a resource element rather than a linked document. The parent representation_variable element identifies that part of the representation that contains the link.

E.g., if an application consists of the resources:

http://example.com/widgets
http://example.com/widgets/{widgetid} (where {widgetid} is a variable component to the URI)

and a GET on the first resource gets me a WidgetList:

<eg:WidgetList xmlns:eg="...">
  <eg:Widget uri="http://example.com/widgets/xyzzy1"/>
  <eg:Widget uri="http://example.com/widgets/abccb1"/>
  ...
</eg:WidgetList>

such that eg:Widget/@uri links to one of the http://example.com/widgets/{widgetid} resources, then this can be described as follows:

<application xmlns:...>

  <resources base="http://example.com/">
    <resource uri="widgets">
      <method href="#widgetList"/>
      <resource id="widgetResource" uri="{widgetid}">
        ...
      </resource>
    </resource>
  </resources>

  <method name="GET" id="widgetList">
    <response>
      <representation mediaType="application/xml" element="eg:WidgetList">
        <representation_variable path="/Widgets/Widget/@uri" repeating="true">
          <link href="#widgetResource" rel="child" rev="index"/>
        </representation_variable>
      </representation>
    </response>
  </method>

</application>

The values of the rel and rev attributes are an open set including those used by convention in HTML. Similar to HTML, a profile attribute may be added to the application element to define a namespace for additional link types.

Documentation

The content model of WADL-defined elements is open for extension and I originally thought that documentation could be added by including html or xhtml elements within a WADL description. Thinking on this some more I've come to the conclusion that it would be better to define a standard documentation element that is an optional first child element of all of the other WADL defined elements and whose content is the documentation for the parent element. E.g.:

<application>

  <documentation><p>An online widget catalogue.</p></documentation>
  
  <resources base="http://example.com/">
    <documentation><p>Commercial widgets.</p></documentation>
    ...
  </resources>
  
</application>

Multi-segment Resource Paths

Its a pain to require multiple nested resource elements when the intermediate resource elements don't represent a useable resource. Relaxing the constraint on the content of the resource/@uri attribute allows you to write:

<resources base="http://example.com/">
  <resource uri="applications/catalogues/widgets">
    ...
  </resource>
</resources>

instead of

<resources base="http://example.com/">
  <resource uri="applications">
    <resource uri="catalogues">
      <resource uri="widgets">
        ...
      </resource>
    </resource>
  </resource>
</resources>

Much more compact and readable !

Matrix URI Support

The path_variable element will be extended with a matrix attribute of type xsd:boolean and default value of "false". When the value of this attribute is "true" the path variable is treated as a matrix variable and is inserted into the uri as a name=value pair with a leading ';' character. E.g.:

<resource uri="widgets">
  <path_variable name="maxPrice" type="xsd:decimal" matrix="true"/>
  <path_variable name="minPrice" type="xsd:decimal" matrix="true"/>
  ...
</resource>

If the value of maxPrice is 10.00 and the value of minPrice is 5.00 then the relative URI of the above resource is:

widgets;maxPrice=10.00;minPrice=5.00

A null value for a matrix path variable results in it being omitted from the uri.

Still on the Drawing Board

Other enhancements still on the drawing board include:

• Shorthand notation for parameterized URIs, e.g. widgets/{widgetid} where {widgetid} in the URI literal takes the place of a path_variable element.
• Support for declaring security requirements.
• Better support for non-XML payloads including JSON.

This work is licensed under a Creative Commons License.