Difference between revisions of "Documentation/WADL conventions"
(→WADL markup conventions) |
(→Writing style) |
||
| Line 11: | Line 11: | ||
== Writing style == | == 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) | ||
| + | |||
| + | === 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) === | ||
| + | |||
| + | === Create methods (POST) === | ||
| + | |||
| + | === Delete methods (DELETE) === | ||
== Markup == | == Markup == | ||
Revision as of 21:36, 20 February 2014
Contents
WADL markup conventions
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)
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)
Create methods (POST)
Delete methods (DELETE)
Markup
For list methods, use the text: "Lists available xxx." Do not use "Gets a listing," or "Prints a listing." For show (or get) methods, use the text: "Shows xxx details." Do not use, "Retrieves information about," or "Gets information for."
