Jump to: navigation, search

Documentation/APISite/DocumentingWadls

< Documentation‎ | APISite
Revision as of 21:56, 21 February 2012 by David (talk)

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.

The wadl vocabulary is fairly simple, but does offer some facilities for authoring convenience, such as referring to methods by reference and defining resources as resources of a certain type. Study the wadl specification and existing wadls to understand how to use these features.

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.

Documenting methods

The wadl <doc> element provides a means for adding documentation to methods, resources, and parameters. Using the technique described above you can include xhtml markup inside the wadl:doc element.

The Rackspace api page generator allows you to distinguish between text intended to provide a brief description of the method and text that provides a longer description. The short description appears even when the method is collapsed. The longer description appears only when the method is opened on the api page. The text that is the short description is flagged with class="shortdesc" so the system will know to show it even when the method is closed:


    <method name="GET" id="getImage">
        <wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="EN" title="Get Image Details">
            <p class="shortdesc">
                List details of the specified image.
            </p>
            <p>
                Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
            </p>
        </wadl:doc>
        <response status="200">
            <representation mediaType="application/xml" element="imageapi:image"/>
            <representation mediaType="application/json" >
            <doc xml:lang="EN">
                <xsdxt:code href="samples/imagedetails.json" />
            </doc></representation>
        </response>
        
    </method>