Difference between revisions of "Documentation/WADL conventions"
(→Short description) |
(→Short description) |
||
| Line 47: | Line 47: | ||
=== Short description === | === Short description === | ||
| − | ==== | + | <pre><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></pre> | ||
| − | '' | + | Make the short description ''short''. Put extra content into subsequent <para> tags. |
| − | + | Follow this convention for short description text: | |
| − | + | {| class="wikitable" | |
| − | + | |- | |
| − | + | ! 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. | ||
| + | |} | ||
=== Create methods (POST) === | === Create methods (POST) === | ||
Revision as of 21:52, 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
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">
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) | List 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. |
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.
