Skip to main content

HATEOAS with WADL

Posted by mhadley on April 2, 2009 at 9:17 AM PDT

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.

Related Topics >>

Comments

RESTful Semantic Web Services

Hello Marc. I've just finished my masters thesis on RESTful Semantic Web Services. One of my findings is that WADL can be successfully applied on Semantic Web Services. I would love to receive some feedback from you! http://www.fullsemanticweb.com/blog/ontologies/restfulgrounding/ Thank you very much in advance. Cheers!

A method definition element can either be a child of a resource element (a local definition) or a child of the application element (a global definition), sorry if that isn't clear from the spec. You should only include id attributes on global definitions to avoid the issue about how/whether to inherit resource-wide parameters in referenced methods.

Hello Marc. I've been researching on WADL lately, and it's been a great experience. However, recently I've got a doubt on the definition of the method element. The WADL specification says the following (p.9): "id: An identifier for the method, required for globally defined methods, not allowed on locally embedded methods". It doesn't make too much sense to me, because the section 2.7.2 talks about the method definition element, which is a child of a resource element. It means that this method is always a locally embedded one. The section 2.7.1 is the one talking about the method reference element, which is the global one. Could you please help me out here? Thanks! Otavio

Hi Marc I am new to REST and WADL stuff and I started using jersey for one of my projects. (jersey-1.1.1.ea-snapshot) I came across lot of articles on wadl particulary using yahoo search api as an example. I understood how to generate client stubs using wadl and wadl2java. But I am not able to understand how an WebApplicationException gets converted to fault element in WADL? For e.g, I have a very simple resource namely Project and it throws EntityNotFoundException (a subclass of WebApplication) . what is the process involved in representing this exception as a fault element in WADL? I took the following steps: Created the Resource 'Project' Created the Exception 'EntityNotFoundException' (subclass of WAE) Used schemagen to generate corresponding xsd's Used wadl-generator to generate wadl from those xsds. However the generated wadl does not contain fault elements like the ones in yahoo search API. Could you please help me figure how to create those fault elements in wadl ? is it a manual process? Thanks in advance