Difference between revisions of "Documentation/WADL conventions"
(→Writing style) |
(→Writing style) |
||
| Line 20: | Line 20: | ||
* Be sure to describe all response fields and response headers. | * Be sure to describe all response fields and response headers. | ||
* Include all possible success and error codes. | * Include all possible success and error codes. | ||
| − | * Include code examples for both JSON and XML if the method has either or both a request body and a response body. | + | * Include code examples for both JSON and XML if the method has either or both a request body and a response body.<br /> |
| + | <br /> | ||
| + | |||
An API method has the following components: | An API method has the following components: | ||
Revision as of 22:00, 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
- Make sure every resource has a unique ID.
- Put the JSON requests before the XML requests, and the JSON responses before the XML responses. Why? JSON is used more commonly than XML.
- Use sentence-style capitalization for method titles.
- Put parameter descriptions inside <param> tags rather than in a table.
- Be sure to describe all parameters - template, headers, plain, and so on.
- Be sure to describe all response fields and response headers.
- Include all possible success and error codes.
- Include code examples for both JSON and XML if the method has either or both a request body and a response body.
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. |
