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.

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

   Register a New Virtual Machine Image. This paragraph is also in the xhtml namespace. 

In this example, the tags and 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  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 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:

  List details of the specified image. 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. ...

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

  The container format refers to whether the virtual machine image is in a	      file format that also contains metadata about the actual virtual machine. 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. You can set your image’s container format to one of the following:   ovf This is the OVF container format   bare This indicates there is no container or metadata envelope for the image   aki This indicates what is stored in Glance is an Amazon kernel image </li>  ari This indicates what is stored in Glance is an Amazon ramdisk image </li>  ami This indicates what is stored in Glance is an Amazon machine image </li></ul> </wadl:doc>

Including Sample Requests and Responses
Include code samples in the 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:

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

= Adding a new wadl to the page = git clone git://github.com/openstack/api-site.git
 * 1) Do a git clone of the openstack/api-site project.

<transformationSet> src/wadls/image-api/src os-image-*.wadl ${project.build.directory}/generated-resources/cloud/normalizeWadl/normalizeWadl.xsl </transformationSet>
 * 1) Add the new WADL in a directory in the   directory.
 * 2) Add a transformationSet to the pom (Note: This step will eventually go away):

mvn clean generate-sources
 * 1) Add a link to the new WADL file in the   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:

= Understanding the use of entities in the existing wadls = TODO: Writeme. Explain how entities are used like macros to reuse certain collections of elements in the wadl.
 * 1) Find the generated page in.