WADL style and markup conventions

In progress......

What is WADL?

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

Writing style

Make sure that every resource has a unique ID. When you include a WADL resource in an XML file, you refer to it by ID.
Put the JSON requests before the XML requests, and the JSON responses before the XML responses. Why? JSON is used more commonly than XML.
Use sentence-style capitalization for method titles.
Put parameter descriptions inside <param> tags rather than in a table.
Be sure to describe all parameters - template, headers, plain, and so on.
Be sure to describe all response fields and response headers.
Include all possible success and error codes.
Include code examples for both JSON and XML if the method has either or both a request body and a response body.

Best practices

Spell-check the WADL.
Remove extra white-space.
Keep descriptions simple.
Use this naming convention for code samples:

JSON: resource_method_type.json. For example, for "create server request," servers_post_request.json.

XML: resource_method_type.xml. For example, for "create server request," servers_post_request.xml.

HTTP header/s: resource_method_lang_http_type.txt. For example, for HTTP headers for a "create server request," servers_post_json_http_request.txt

Validate code samples. Use oXygen to validate XML examples. Use http://jsonformatter.curiousconcept.com/#jsonformatter to validate JSON.

Mark-up

URI

Parameters

The correct location for parameters is one of these locations:

As a child of a resource:

<resource id="tenant_id" path="{tenant_id}">
    <param name="tenant_id" style="template" type="xsd:string">
        <wadl:doc xmlns="http://docbook.org/ns/docbook"  xml:lang="EN" title="Tenant ID">
            <para>The ID for the tenant or account in a multi-tenancy cloud.</para>
        </wadl:doc>
    </param>
       . . .
</resource>

As a child of a request or response representation, before the ending </representation> tag. Preferably, place inside the XML representation:

<request>
    <representation mediaType="application/json">
        <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN" title="Pause server: JSON request">
            <xsdxt:code href="../api_samples/os-admin-actions/admin-actions-pause.json"/>
        </wadl:doc>
    </representation>
    <representation mediaType="application/xml">
        <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN" title="Pause server: XML request">
            <xsdxt:code href="../api_samples/os-admin-actions/admin-actions-pause.xml"/>
        </wadl:doc>
        <param name="pause" style="plain" type="xsd:string" required="true">
            <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN" title="Pause action">
                <para>Specify the <code>pause</code> action in the request body.</para>
            </wadl:doc>
        </param>
    </representation>
</request>

Title

<method name="GET" id="getVolume">
        <wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="EN"
            title="Show volume details">

Use sentence-style capitalization for the title.

Follow this convention for title text:

Method	Example title
Create (POST)	Create volume
List (GET)	List volumes
Show (GET)	Show volume details
Update (PUT)	Update volume
Delete (DELETE)	Delete volume

Short description

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

Make the short description short. Put extra content into subsequent <para> tags.

Follow this convention for short description text:

Method	Example short description	Do not use
Create (POST)	Creates a volume.	Create a volume. Creates a new volume.
List (GET)	Lists volumes.	Gets a listing of volumes. Prints a listing of volumes. Retrieves a list of volumes.
Show (GET)	Shows volume details. Shows image details. Shows the up time for a specified hypervisor.	Retrieves information about, or Gets information for.
Update (PUT)	Updates volume details.
Delete (DELETE)	Deletes a volume.	Removes a volume. Permanently destroys a volume.

Documentation/WADL conventions

Contents