Difference between revisions of "Documentation/WADL conventions"
(→WADL markup conventions) |
(→WADL markup conventions) |
||
Line 1: | Line 1: | ||
{{OpenStack_Documentation_Navbar}} | {{OpenStack_Documentation_Navbar}} | ||
− | = WADL markup conventions = | + | = WADL style and markup conventions = |
In progress...... | In progress...... | ||
Line 28: | Line 28: | ||
* Sample JSON and XML response bodies (if present) | * Sample JSON and XML response bodies (if present) | ||
− | === List methods (GET) === | + | === URI === |
+ | |||
+ | === Title === | ||
+ | |||
+ | Specify the title for a method as follows: | ||
+ | |||
+ | <sub><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> | ||
+ | </wadl:doc> | ||
+ | <response status="200"> | ||
+ | <representation mediaType="application/xml"> | ||
+ | <wadl:doc xmlns="http://docbook.org/ns/docbook" | ||
+ | xml:lang="EN"> | ||
+ | <xsdxt:code href="samples/volume_show.xml"/> | ||
+ | </wadl:doc> | ||
+ | </representation> | ||
+ | <representation mediaType="application/json"> | ||
+ | <wadl:doc xmlns="http://docbook.org/ns/docbook" | ||
+ | xml:lang="EN"> | ||
+ | <xsdxt:code href="samples/volume_show.json"/> | ||
+ | </wadl:doc> | ||
+ | </representation> | ||
+ | </response> | ||
+ | </method></sub> | ||
+ | |||
+ | === Short description === | ||
+ | |||
+ | ==== List methods (GET) ==== | ||
'''Short description:''' Use the text: "Lists available xxx." Do not use "Gets a listing," or "Prints a listing." | '''Short description:''' Use the text: "Lists available xxx." Do not use "Gets a listing," or "Prints a listing." | ||
− | === Show methods (GET) === | + | ==== 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." | '''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) === | + | ==== Update methods (PUT) ==== |
+ | |||
+ | Short description: Use the text: "Updates xxx." | ||
=== Create methods (POST) === | === Create methods (POST) === | ||
− | === Delete methods (DELETE) === | + | 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 == | == Markup == |
Revision as of 21:38, 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"> <para role="shortdesc">Shows volume details.</para> </wadl:doc> <response status="200"> <representation mediaType="application/xml"> <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"> <xsdxt:code href="samples/volume_show.xml"/> </wadl:doc> </representation> <representation mediaType="application/json"> <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"> <xsdxt:code href="samples/volume_show.json"/> </wadl:doc> </representation> </response> </method>
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.