Revision as of 21:42, 2 March 2014

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"'''>
          ...
</method>

Use sentence-style capitalization for the title.

Follow this convention for title text:

• For create methods, "Create volume"
• For list methods, "List volumes"
• For get methods for a single item, "Show volume details"
• For update methods, "Update volume"
• For delete methods, "Delete volume"

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.