Jump to: navigation, search

Documentation/WADL conventions

< Documentation
Revision as of 17:22, 16 May 2014 by Rose (talk | contribs) (deleted link to Writers Guide at docs.rackspace.com; it's not there and never has been, and the link is generating 404s at Rackspace. The only public-facing version of this I remember was hosted at openstack.org but I can't find it now.)

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



Mark-up

URI

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.