Jump to: navigation, search

Difference between revisions of "Documentation/WADL conventions"

(deleted link to Writers Guide at docs.rackspace.com; it's not there and never has been, and the link is generating 404s at Rackspace. The only public-facing version of this I remember was hosted at openstack.org but I can't find it now.)
 
(31 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
{{OpenStack_Documentation_Navbar}}
 
{{OpenStack_Documentation_Navbar}}
 +
{{OpenStack_Conventions_Navbar}}
  
= WADL style and markup conventions =
+
{{Warning|header=Warning|body=This page is deprecated. It is left here for reference.}}
  
In progress......
+
This page provides WADL style and markup conventions and is work in progress.
 +
 
 +
__TOC__
  
 
== What is WADL? ==
 
== What is WADL? ==
Line 18: Line 21:
 
* Be sure to describe all response fields and response headers.
 
* Be sure to describe all response fields and response headers.
 
* Include all possible success and error codes.
 
* 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.<br />
+
* Include code examples for both JSON and XML if the method has either or both a request body and a response body.
<br />
 
  
 
== Best practices ==
 
== Best practices ==
Line 30: Line 32:
 
:XML: resource_method_type.xml. For example, for "create server request," servers_post_request.xml.
 
: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
 
: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://jsonformatter.curiousconcept.com/#jsonformatter to validate JSON.<br />
+
* Validate code samples. Use oXygen to validate XML examples. Use http://trentm.com/json/ command-line tool to format and validate JSON.  
<br />
+
:For example:
 +
:<pre>json -o json-4 -f KeyCreateRequest.json</pre>
 +
 
 +
== Mark-up ==
 +
 
 +
=== Parameters ===
 +
 
 +
The correct location for parameters is one of these locations:
  
 +
As a child of a resource:
  
== Mark-up ==
+
<pre>
 +
<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>
 +
        </wadl:doc>
 +
    </param>
 +
      . . .
 +
</resource>
 +
</pre>
  
 +
As a child of a request or response representation, before the ending </representation> tag. Preferably, place inside the XML representation:
  
=== URI ===
+
<pre>
 +
<request>
 +
    <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"/>
 +
        </wadl:doc>
 +
    </representation>
 +
    <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"/>
 +
        </wadl:doc>
 +
        <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>
 +
            </wadl:doc>
 +
        </param>
 +
    </representation>
 +
</request>
 +
</pre>
  
 
=== Title ===
 
=== Title ===
Line 45: Line 83:
 
             title="Show volume details"></pre>
 
             title="Show volume details"></pre>
  
Use sentence-style capitalization for the title. <br />
+
Use sentence-style capitalization for the title.
 
 
 
Follow this convention for title text:
 
Follow this convention for title text:
  
Line 90: Line 127:
 
|}
 
|}
  
 +
== Troubleshooting validation errors ==
 +
If your build for a book that references a WADL breaks with a validation error, like this:
 +
 +
<pre>
 +
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
 +
</pre>
 +
 +
Complete these steps to diagnose the issue:
 +
 +
# Open the '''*-invalid-idrefs.xml''' file in oXygen. In this example, you would open '''identity-dev-guide.xml-invalid-idrefs.xml'''.
 +
# Validate the file and go the first line in error.
 +
# View in '''Author''' mode.
 +
# Scroll up to find the closest method - this is usually the method that's in error.
 +
# 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 ===
 +
 +
# 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.
 +
# 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:&nbsp;
 +
 +
<pre><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"></pre>
 +
 +
=== WADL issue ===
 +
 +
# Open the erroneous WADL file in oXygen.
 +
# Navigate to the method that's in error.
 +
# Look for missing IDs, duplicate IDs, and incorrect mark-up.
 +
# 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.
  
 +
----
 
[[Category:Documentation]]
 
[[Category:Documentation]]

Latest revision as of 13:48, 27 March 2018

Warning icon.svg Warning

This page is deprecated. It is left here for reference.

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

Mark-up

Parameters

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>
        </wadl:doc>
    </param>
       . . .
</resource>

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

<request>
    <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"/>
        </wadl:doc>
    </representation>
    <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"/>
        </wadl:doc>
        <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>
            </wadl:doc>
        </param>
    </representation>
</request>

Title

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