Documentation/APISite/DocumentingWadls

What is a WADL?

WADL, Web Application Description Language, is an XML vocabulary for describing restful APIs. The WADL Specification defines this vocabulary and provides XML schemas for validating wadl documents.

Rackspace maintains a customized version of the oXygen XML editor to make it easier to write wadl files by providing on-the-fly validation, tag completion, and so on.

Understanding Namespaces

XML Namespaces allow you to mix different xml vocabularies in a single document. In wadl files, you typically find a number of namespaces declared. The wadl tags themselves are in the http://wadl.dev.java.net/2009/02 namespace. So on the root element of the wadl might find the following declarations:

<application 
   xmlns="http://wadl.dev.java.net/2009/02"
   xmlns:wadl="http://wadl.dev.java.net/2009/02"
...

The first of these declares that the current default namespace is the wadl namespace. The second declaration maps the wadl namespace to the local prefix "wadl". Why would you want to declare both of these namespaces? One reason is so that you can do the following:

<resource id="Images" path="images">
    <method name="POST" id="createImage">
        <wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="EN" title="create Image">
            <p>Register a New Virtual Machine Image.</p>
            <p>This paragraph is also in the xhtml namespace.</p>
        </wadl:doc>

In this example, the tags <resource> and <method> are in the default wadl namespace. The wadl:doc tag, however, uses the wadl prefix so that it is possible to change the default namespace to the xhtml namespace: xmlns="http://www.w3.org/1999/xhtml". Now all of the children of the <wadl:doc> element are in the xhtml namespace by default. This technique allows you to mix wadl and xhtml elements with a minimal use of namespace prefixes.