Difference between revisions of "Documentation/WADL conventions"
(→Title) |
(→Title) |
||
| Line 24: | Line 24: | ||
title="Show volume details"></pre> | title="Show volume details"></pre> | ||
| − | + | Use sentence-style capitalization for the title. <br /> | |
| − | |||
| − | :{| class="wikitable" | + | Follow this convention for title text: |
| − | + | ||
| − | + | {| class="wikitable" | |
| − | + | |- | |
| − | + | ! 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 === | === 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. |
