Jump to: navigation, search

Documentation/APISite/DocumentingWadls

< Documentation‎ | APISite
Revision as of 04:09, 24 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.

Validation

Oxygen automatically validates the document when you open it and as you type. If you need to force it to revalidate, use the menu item Document->Validation->Reset Cache and Validate or the corresponding button. Oxygen validates both against the XSD that defines the wadl and a set of schematron rules that we have added. If you find some type of error that is not yet caught by an existing schematron rule, please let the Rackspace <<MailTo(clouddoctoolsteam AT lists DOT rackspace DOT com, Doc Tools Team)>> know.

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

Short descriptions

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.

In the following example, "List details of the specified image." appears even when the method is collapsed in the api reference page, while the "Lorem ipsum" paragraph appears only when it is expanded:


    <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>
...


Documenting params

Likewise, you can document parameters in the same way. However, the shortdesc class does not apply here:


<param name="container_format" style="plain" type="xsd:string" required="true">
       <wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="EN" title="Container Formats">
	   <p>The container format refers to whether the virtual machine image is in a
	       file format that also contains metadata about the actual virtual machine.</p>
	   <p>There are two main types of container formats: OVF and Amazon’s AMI. In
	       addition, a virtual machine image may have no container format at all –
	       basically, it’s just a blob of unstructured data.</p>
	   <p>You can set your image’s container format to one of the following:</p>
	   <ul>
	       <li><p><strong>ovf</strong></p>
		   <p>This is the OVF container format</p>
	       </li>
	       <li><p><strong>bare</strong></p>
		   <p>This indicates there is no container or metadata envelope for the image</p>
	       </li>
	       <li><p><strong>aki</strong></p>
		   <p>This indicates what is stored in Glance is an Amazon kernel image</p>
	       </li>
	       <li><p><strong>ari</strong></p>
		   <p>This indicates what is stored in Glance is an Amazon ramdisk image</p>
	       </li>
	       <li><p><strong>ami</strong></p>
		   <p>This indicates what is stored in Glance is an Amazon machine image</p></li></ul>
       </wadl:doc>
</param>   


Including Sample Requests and Responses

Include code samples in the <representation> elements for the response or request. The build process will make it possible to select XML or JSON from a dropdown to show the desired sample:


        <response status="200">
           <representation mediaType="application/xml" element="imageapi:image">
            <doc xml:lang="EN">
                <xsdxt:code href="samples/imagedetails.xml" />
            </doc>
           </representation>
           <representation mediaType="application/json" >
            <doc xml:lang="EN">
                <xsdxt:code href="samples/imagedetails.json" />
            </doc>
           </representation>
        </response>


Adding a new wadl to the page

  1. Do a git clone of the openstack-manuals project.
git clone git://github.com/openstack/openstack-manuals.git
  1. Add the new WADL in a directory in the doc/src/docbkx/openstack-api-site/src/wadl directory.
  2. Add a transformationSet to the pom (Note: This step will eventually go away):
<transformationSet>
  <dir>src/wadls/image-api/src</dir>
  <includes>
   <include>os-image-*.wadl</include>
  </includes>
  <stylesheet>${project.build.directory}/generated-resources/cloud/normalizeWadl/normalizeWadl.xsl</stylesheet>
</transformationSet>
  1. Add a link to the new WADL file in the doc/src/docbkx/openstack-api-site/src/docbkx/index.xml file. You can point to individual resource+method combinations or to a resource to include all of the methods in that resource or to an entire wadl to include all the the resource+method combinations in that wadl.
  2. In the directory with the pom.xml, run:
mvn clean generate-sources 
  1. Find the generated page in {{[target/docbkx/html</nowiki></pre>

.