Documentation/WADL conventions

This page provides WADL style and markup conventions and is work in progress.

What is WADL?
For complete information about the WADL language, see Web Application Description Language (http://www.w3.org/Submission/wadl/).

Writing style

 * Make sure that every resource has a unique ID. When you include a WADL resource in an XML file, you refer to it by 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 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.

Best practices

 * Spell-check the WADL.
 * Remove extra white-space.
 * Keep descriptions simple.
 * Use this naming convention for code samples:
 * JSON: resource_method_type.json. For example, for "create server request," servers_post_request.json.
 * XML: resource_method_type.xml. For example, for "create server request," servers_post_request.xml.
 * HTTP header/s: resource_method_lang_http_type.txt. For example, for HTTP headers for a "create server request," servers_post_json_http_request.txt


 * Validate code samples. Use oXygen to validate XML examples. Use http://trentm.com/json/ command-line tool to format and validate JSON.
 * For example:
 * json -o json-4 -f KeyCreateRequest.json

Parameters
The correct location for parameters is one of these locations:

As a child of a resource:

   The ID for the tenant or account in a multi-tenancy cloud.  . ..

As a child of a request or response representation, before the ending tag. Preferably, place inside the XML representation:

          Specify the  action in the request body. 

Title
 

Use sentence-style capitalization for the title. Follow this convention for title text:

Short description
<method name="GET" id="getVolume">  Shows volume details.

Make the short description short. Put extra content into subsequent tags.

Follow this convention for short description text:

Troubleshooting validation errors
If your build for a book that references a WADL breaks with a validation error, like this:

2014-07-27 21:20:15.285 | @@@@@@@@@@@@@@@@@@@@@@ 2014-07-27 21:20:15.285 | !!!VALIDATION ERRORS!! 2014-07-27 21:20:15.285 | !!!!!!!!!!!!!!!!!!!!!! 2014-07-27 21:20:15.285 | 2014-07-27 21:20:15.285 | Note: Open the temporary file: 2014-07-27 21:20:15.285 | 2014-07-27 21:20:15.285 | file:/home/jenkins/workspace/gate-identity-api-tox-doc-publish-checkbuild/v2.0/target//identity-dev-guide.xml-invalid-idrefs.xml

Complete these steps to diagnose the issue:


 * 1) Open the *-invalid-idrefs.xml file in oXygen. In this example, you would open identity-dev-guide.xml-invalid-idrefs.xml.
 * 2) Validate the file and go the first line in error.
 * 3) View in Author mode.
 * 4) Scroll up to find the closest method - this is usually the method that's in error.
 * 5) Clone and build the api-site/api-ref pom.xml file. If this builds successfully, the issue is in the source DocBook file and not in the WADL file. If this does not build successfully, the issue is in the WADL file.

DOCBOOK file issue

 * 1) Find the chapter file in api-site/api-ref that matches the file that is breaking. For example, if identity-api/v2.0/src/ch_identity-client-api.xml is the source of the error, find the parallel api-site/api-ref/src/docbkx/ch_identity-v2.xml file.
 * 2) Open both ch_identity-client-api.xml and ch_identity-v2.xml in oXygen and compare these files. Update the references to the WADL in ch_identity-client-api.xml to match those in ch_identity-v2.xml. However, make sure to point to the raw version of the WADL, like this:

<wadl:resource href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/identity-api/src/v2.0/wadl/identity-admin.wadl#admin-extensions">

WADL issue

 * 1) Open the erroneous WADL file in oXygen.
 * 2) Navigate to the method that's in error.
 * 3) Look for missing IDs, duplicate IDs, and incorrect mark-up.
 * 4) If you cannot find the error, look in the DocBook file that references this WADL. Look for duplicate calls to the same method. Look for incorrect method calls - for example, the name of the method changed, but the reference to the method is to the older method name.