Craig asked me how you would describe something like the Sun Cloud APIs with WADL and I thought others might be interested in the answer. A key feature of the cloud APIs is that they make good use of hypertext as the engine of application state or HATEOAS for (relatively) short. What this means is that rather than documenting a set of URIs and URI templates and relying on the client to construct URIs to access the resource they need, the cloud APIs only publish a single "root" URI and then document where to find additional URIs in representations that clients can use to traverse the service. This is much closer to how a browser user traverses links in web pages. In a recent blog entry Craig describes the advantages of HATEOAS.

So, how to describe this kind of Web application in WADL ? The key is to:

1. Use resource types to describe each kind of resource,
2. Parameterize representations to identify links embedded within them,
3. Define the types of resource each embedded link identifies.

To illustrate I'll use the Sun cloud APIs and the root level representation of the VDC. In WADL we describe this top level resource as follows:

<resources base="http://example.com/">
  <resource path="/" type="#vdc"/>
</resources>

The above declares a top level resource of type "vdc" at the URI "http://example.com/". Next we need to describe the resource type "vdc":

<resource_type id="vdc">
  <method name="GET">
    <response status="200">
      <representation mediaType="application/vnd.com.sun.cloud.compute.Vdc+json">
        <parameter name="attach" path="vms[].attach" style="plain">
          <link resource_type="#button"/>
        </parameter>
        <parameter name="detach" path="vms[].detach" style="plain">
          <link resource_type="#button"/>
        </parameter>
        <parameter name="backup" path="vms[].backup" style="plain">
          <link resource_type="#button"/>
        </parameter>
        ...
      </representation>
    </response>
  </method>
</resource_type>

The above says that a representation of resources of type "vdc" can be obtained with GET and that such representations contain links to other types of resources. I've shown three links here but in reality a VDC document contains many more. Each link is contained within a parameter that describes where in the representation the link can be found. In this case each link is to the same type of resource that essentially acts like a push button, here's the description of that resource type:

<resource_type id="button">
  <method name="POST">
    <response status="204">
  </method>
</resource_type>

The above says that resources of type "button" only support POST and return an empty 204 response on success.

I've glossed over one important issue related to the use of JSON for the representation of a VDC. If the representation used XML then the value of the path attribute of the parameter element is an XPath and it has semantics for selecting a set of nodes. For JSON theres no such standard path language (that I'm aware of) so I've had to improvise. The "vms" property of the vdc JSON object is an array and the "[]" in the path attribute values is meant to signify that the path will match multiple properties of the JSON object, if anyone has a better idea then let me know.

A draft of the JAX-RS 1.1 specification and API is now available. We're now working on implementing the new features in Jersey and adding corresponding tests to the TCK. It will be a while before 1.1 can be declared final since there's quite a bit of new functionality, particularly in the areas of integration with Servlet 3.0, EJB 3.1 and JSR 299 - none of which are yet final.

Check out this tutorial on the use of WADL to add a service to Zembly. For those not already familiar with Zembly it is:

"An application development environment that not only targets the web as its native platform, but uses cutting-edge web innovations such as web services, social networking, and Web 2.0, to change the way applications are built, deployed, scaled, and delivered to where users congregate."

Essentially any service described by WADL can be easily used within a Zembly application. If you are using Jersey to build your service then support for WADL comes free.

Its been just over two years since the last version of WADL was published and, in the intervening time, a number of issues have accumulated. I've held off making regular updates for reasons of stability but I think there's sufficient backlog now to require a new version. First drafts of the updated specification and schemas are available at:

• http://wadl.dev.java.net/wadl20090202.pdf
• http://wadl.dev.java.net/wadl20090202.rnc
• http://wadl.dev.java.net/wadl20090202.xsd

Changes since the November 2006 Publication:

• The XML namespace name was changed to http://wadl.dev.java.net/2009/02.
• Resolved issue 13. The status attribute was moved from the representation element to the response element. The cardinality of the response element was changed from 0–1 to 0–many. The fault element was removed.
• Resolved issue 17. Allow parameters at top level and parameter references to prevent repetition when a parameter is used in multiple places.
• Resolved issue 18. A resource type element may now contain resource child elements.
• Resolved issue 20. Allow multiple resources elements within an application.
• Updated the Atompub example to RFC syntax.

Unfortunately the changes required by issue 13 are not backwards compatible hence the namespace change. Existing WADL docs will require minor edits as a result.

All feedback on the new draft is welcome. Now would be a good time to file bug reports or request enhancements.