Jump to: navigation, search

Difference between revisions of "Documentation/WADL conventions"

(Markup)
(Title)
Line 19: Line 19:
  
 
=== Title ===
 
=== Title ===
 +
 +
==== Markup ====
  
 
Specify the title for a method as follows:
 
Specify the title for a method as follows:
Line 26: Line 28:
 
             title="Show volume details"></pre>
 
             title="Show volume details"></pre>
  
Use sentence-style capitalization for the title.
+
==== Writing style ====
  
Follow this convention for title text:
+
* Use sentence-style capitalization for the title.
 +
* Follow this convention for title text:
  
 
{| class="wikitable"
 
{| class="wikitable"

Revision as of 21:55, 2 March 2014

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

Markup

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">

Writing style

  • 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.