Provide WADL files for the Quantum API

Registered by Salvatore Orlando on 2011-10-11

As a part of the documentation effort, we will also provide a WADL file for the Quantum API.
The WADL file will allow users of the Quantum API to automatically generate stubs for using the API itself.

== TODO list summary ==

1. Need XSD to represent plural attr_types and None's
   There are expression limits in the WADL syntax that it is essential to use XSD to describe Nil, list, string_or_none, etc. data structures. There is a blueprint quantum-api-xsd filed for future work. Once the XSD files are generated, WADL files will import the XSD files and utilize them.

2. Remove hard coding in DELETE return codes and apply multiple return codes for GET, POST, and PUT
   Quantum is fortunate enough to have RESOURCE_ATTR_MAPS which is helps writing scripts that generate WADL files. However currently it is cumbersome to know every positive and negative return codes and results for all HTTP method calls. We should devise a way to put all return cases in a RESOURCE_ATTR_MAPS style dict to automatically generate all response cases in WADL files.

3. Process extended resources
    Each API extension has a method called get_extended_resources() which alone is not a classmethod. The extended resources are not shown in the currently version of WADL files and should be used in the next steps.

4. Make use of extension namespace
    Current WADL files only uses the "http://openstack.org/quantum/api/v2.0" uri as "quantum" namespace. However each extension has a namespace which could be retrieved by get_namespace(). We should decide whether or not to use these namespaces and how to apply then if we choose to use.

Blueprint information

Status:
Complete
Approver:
Salvatore Orlando
Priority:
Medium
Drafter:
None
Direction:
Needs approval
Assignee:
None
Definition:
Obsolete
Series goal:
None
Implementation:
Needs Code Review
Milestone target:
None
Started by
Zhongyue Luo
Completed by
Armando Migliaccio

Whiteboard

Dan
I want He jie xu to deal with it. ideas?

Yong: that would be great. I'd probably reach out to others on the mailing list to see who is doing this for other projects, and whether there are tools they have already standardized on. Want to make sure we aren't re-inventing the wheel.

we can follow what nova integrated tests has done to auto generates api samples and docs.
 --Yaguang

I wrote a specification at http://wiki.openstack.org/Quantum/API/WADL
--zyluo

zyluo:
Will u tell u how we can use it to help test, document writing and so on? We can get some experience from nova just as said by Yaguang. And u can grab this BP to u.
--yong

Yaguang is referring to this bp https://blueprints.launchpad.net/nova/+spec/nova-api-samples
I'll take a look and fill in your question
--zyluo

Nova has manually created json/XML samples of each REST API's request and response in nova/doc/api_samples. These sample files help Nova documentation by using them in api.openstack.org and in the Nova administor manual.

Each of the sample files also have a template file in nova/tests/integrated/api_samples. These template files are utilized when running integration tests by replacing placeholders with real values according to the nova.conf file at runtime.

This BP should be responsible of creating WADL files for Quantum REST APIs. These WADL files will automatically generate API sample files and templates that will be used in manuals and integration tests respectively in the next phase of development.
--zyluo

Gerrit topic: https://review.openstack.org/#q,topic:bug/1102927,n,z

Addressed by: https://review.openstack.org/20222
    Fix all extension contract classes inherit from extensions.ExtensionDescriptor

Gerrit topic: https://review.openstack.org/#q,topic:bug/1104882,n,z

Addressed by: https://review.openstack.org/20465
    Adds API parameters to quantum.api.extension.ResourceExtension

Update 2013-01-28

We have some patches under review, although it does not seem they complete the work.
I am keeping it targeted for G-3 at the moment.

Gerrit topic: https://review.openstack.org/#q,topic:bp/quantum-api-wadl,n,z

Addressed by: https://review.openstack.org/21038
    Quantum API WADL doc generation

(?)

Work Items

This blueprint contains Public information 
Everyone can see this information.