Marc Hadley's Blog

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.

Comments

• I like documentation as its own element. It will keep things much cleaner.

  Ditto for the URI pathing. I assume the new pathing syntax means you are not required to explicitly describe the elements of the path, yes? By the same token, could those parent elements later be described on their own, a la..

  resource uri="my/nested/service"
  ...
  /resource
  ...
  resource uri="my/nested"
  ...
  /resource

  and so on?

  Posted by: headius on June 30, 2006 at 03:02 PM

• I think to do that you'd break up the resource into one with a path of "my/nested" with a nested sub-resource of "service".

  Posted by: mhadley on June 30, 2006 at 07:39 PM

• I like documentation as its own element. It will keep things much cleaner. Ditto for the URI pathing
  

  Posted by: oscar88 on December 22, 2006 at 02:00 AM

• Although resource references are great from an authoring and from a rest pov, it does introduce the obvious consequence that one resource identified by one id can now be mapped to more than one URI. How do we reuse the URI Template for a resource when generating representations contains references to it?

  My point is not that resource references should not be introduced into WADL, but that we need to consider both, client and implementation, sides interacting with an WADL spec. As someone that will implement (map resources to my domain objects) an WADL specification I would like to reuse a URI Template defined for a resource when generating representations that contain links to these resources. It is quite common to see XSL stylesheets or JSP pages, for instance, duplicating the URI Template when it would be a lot nicer to be able to logically refer to a resource URI as a function of a list of parameters producing the actual URI Template specified in the WADL specification. If a resource has more than one URI how to disambiguate?

  It would be nice if WADL had someway to specify what is the default URI Template for a resource so that there would be no ambiguities generating a resource URI from a resource id on the way out while still supporting multiple URIs for a single resource on the way in.

  Posted by: ydewit on March 09, 2007 at 08:08 PM

• Resource references turned out to be complex for a number of reasons, the ones you cite amongst them. The latest rev of the spec replaces resource references with resource types and makes the link element reference a resource type rather than a resource. Please see http://wadl.dev.java.net for the latest revision of the specification.

  Posted by: mhadley on March 12, 2007 at 07:15 AM

This work is licensed under a Creative Commons License.