Jump to: navigation, search

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

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




The correct location for parameters is one of these locations:

As a child of a resource:

<resource id="tenant_id" path="{tenant_id}">
    <param name="tenant_id" style="template" type="xsd:string">
        <wadl:doc xmlns="http://docbook.org/ns/docbook"  xml:lang="EN" title="Tenant ID">
            <para>The ID for the tenant or account in a multi-tenancy cloud.</para>
       . . .

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

    <representation mediaType="application/json">
        <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN" title="Pause server: JSON request">
            <xsdxt:code href="../api_samples/os-admin-actions/admin-actions-pause.json"/>
    <representation mediaType="application/xml">
        <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN" title="Pause server: XML request">
            <xsdxt:code href="../api_samples/os-admin-actions/admin-actions-pause.xml"/>
        <param name="pause" style="plain" type="xsd:string" required="true">
            <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN" title="Pause action">
                <para>Specify the <code>pause</code> action in the request body.</para>


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

Troubleshooting build issues

Validation errors

If your build for a book that references a WADL breaks with an like the following error:

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
2014-07-27 21:20:15.285 | 
2014-07-27 21:20:15.285 | to see all the errors in context. 
2014-07-27 21:20:15.285 | You must correct the errors in the original 
2014-07-27 21:20:15.286 | source DocBook or wadl files however.
2014-07-27 21:20:15.286 | 
2014-07-27 21:20:15.286 | You can control whether build fails or not by 
2014-07-27 21:20:15.286 | setting failOnValidationError to no in your pom. 

Complete these steps to diagnose the issue:

  1. . xx