Difference between revisions of "Documentation/WADL conventions"
(→Writing style) |
|||
Line 14: | Line 14: | ||
An API method has the following components: | An API method has the following components: | ||
− | {{ | + | {{OpenStack_Documentation_toc}} |
=== URI === | === URI === |
Revision as of 21:47, 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: Template:OpenStack Documentation toc
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
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.