Difference between revisions of "Documentation/WADL conventions"
(→Title) |
(→Title) |
||
Line 27: | Line 27: | ||
* Follow this convention for title text: | * Follow this convention for title text: | ||
− | {| class="wikitable" | + | :{| class="wikitable" |
− | |- | + | :|- |
− | ! Method !! Example title | + | :! Method !! Example title |
− | |- | + | :|- |
− | | Create (POST) || Create volume | + | :| Create (POST) || Create volume |
− | |- | + | :|- |
− | | List (GET) || List volumes | + | :| List (GET) || List volumes |
− | |- | + | :|- |
− | | Show (GET) || Show volume details | + | :| Show (GET) || Show volume details |
− | |- | + | :|- |
− | | Update (PUT) || Update volume | + | :| Update (PUT) || Update volume |
− | |- | + | :|- |
− | | Delete (DELETE) || Delete volume | + | :| Delete (DELETE) || Delete volume |
− | |} | + | :|} |
+ | : | ||
=== Short description === | === Short description === |
Revision as of 21:56, 2 March 2014
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.