WADL style and markup conventions

In progress......

What is WADL?

For information about WADL files, see http://docs.rackspace.com/writers-guide/content/ch_wadl.html.

For complete information about the WADL language, see Web Application Description Language (http://www.w3.org/Submission/wadl/).

Writing style

An API method has the following components:

URI
Title
Short description
Long description
Success codes
Request parameter descriptions
Sample HTTP requests
Sample JSON and XML request bodies (if present)
Error codes
Response parameter descriptions
Sample HTTP responses
Sample JSON and XML response bodies (if present)

URI

Title

Specify the title for a method as follows:

_{<method name="GET" id="getVolume">}

       <wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="EN"
           title="Show volume details">
           <para role="shortdesc">Shows volume details.</para>
       </wadl:doc>
       <response status="200">
           <representation mediaType="application/xml">
               <wadl:doc xmlns="http://docbook.org/ns/docbook"
                   xml:lang="EN">
                   <xsdxt:code href="samples/volume_show.xml"/>
               </wadl:doc>
           </representation>
           <representation mediaType="application/json">
               <wadl:doc xmlns="http://docbook.org/ns/docbook"
                   xml:lang="EN">
                   <xsdxt:code href="samples/volume_show.json"/>
               </wadl:doc>
           </representation>
       </response>
   </method>

Short description

List methods (GET)

Short description: Use the text: "Lists available xxx." Do not use "Gets a listing," or "Prints a listing."

Show methods (GET)

Short description: Use the text: "Shows xxx details" or "Shows the xx for a specified xx." Do not use, "Retrieves information about," or "Gets information for." For example: "Shows image details," or "Shows the up time for a specified hypervisor."

Update methods (PUT)

Short description: Use the text: "Updates xxx."

Create methods (POST)

Short description: Use the text: "Creates a xxx." Do not use, "Creates a new xxx." The word "creates" implies a new resource.

Delete methods (DELETE)

Short description: Use the text: "Deletes a xxx," or "Deletes a specified xxx."

Markup

TBD.

Documentation/WADL conventions

Contents