Documentation/WADL conventions
Contents
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:
<pre> <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> </pre>
As a child of a request or response representation, before the ending </representation> tag. Preferably, place inside the XML representation:
<pre> <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> </pre>
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. |