Difference between revisions of "Documentation/WADL conventions"
(→Title) |
(→Title) |
||
| Line 35: | Line 35: | ||
<pre><method name="GET" id="getVolume"> | <pre><method name="GET" id="getVolume"> | ||
| − | <wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="EN" | + | <wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="EN" title="Show volume details"></pre> |
Use sentence-style capitalization for the title. | Use sentence-style capitalization for the title. | ||
| Line 41: | Line 41: | ||
Follow this convention for title text: | Follow this convention for title text: | ||
| − | + | {| class="wikitable" | |
| − | + | |- | |
| − | + | ! 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 === | === Short description === | ||
Revision as of 21:45, 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
- Short description
- Long description
- Success codes
- Request parameter descriptions
- Sample HTTP requests
- Sample JSON and XML request bodies (if present)
- Error codes
- Response parameter descriptions
- Sample HTTP responses
- Sample JSON and XML response bodies (if present)
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.
