Revision as of 13:49, 23 June 2014

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>

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:

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: