Documentation/WADL conventions
Contents
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
<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.