Jump to: navigation, search

Difference between revisions of "Neutron/API/WADL"

m (ThierryCarrez moved page Quantum/API/WADL to Neutron/API/WADL)
 
(16 intermediate revisions by 3 users not shown)
Line 1: Line 1:
__NOTOC__
+
 
 
= Quantum API WADL Specification =
 
= Quantum API WADL Specification =
 
[https://blueprints.launchpad.net/quantum/+spec/quantum-api-wadl blueprint link]
 
[https://blueprints.launchpad.net/quantum/+spec/quantum-api-wadl blueprint link]
Line 5: Line 5:
 
== Resources ==
 
== Resources ==
 
* http://www.w3.org/Submission/wadl/
 
* http://www.w3.org/Submission/wadl/
* http://code.w3.org/unicorn/attachment/wiki/how_to_write_new_contract/css-validator.wadl
 
  
 
== Scope ==
 
== Scope ==
Provide WADL documents for the Quantum APIs.
+
Provide WADL documents for the Quantum core API and API extensions.
  
 
WADL document scope
 
WADL document scope
 +
 
* Core APIs will have a WADL document
 
* Core APIs will have a WADL document
 
* All extension APIs will have its own WADL document
 
* All extension APIs will have its own WADL document
Line 17: Line 17:
 
* A '''resources''' component will have '''resource''' components for each resource entity
 
* A '''resources''' component will have '''resource''' components for each resource entity
 
** eg) network, subnet, port, etc.
 
** eg) network, subnet, port, etc.
* Each '''resource''' component will have '''method''' components for GET, POST, PUT, and DELETE.
+
* Each '''resource''' component will have '''method''' components for GET(list, show), POST(create, bulk create), PUT(update), and DELETE(delete).
* Each '''method''' component will have a '''request''' component and '''''WILL NOT HAVE''''' a '''response''' component
+
* Each '''method''' component will have a '''request''' component and a optional '''response''' component
* A '''request''' component will have '''param''' components based on the API spec
+
* A '''request''' or '''response''' component will have '''representation''' components composed with '''param''' components based on the attribute resource map of the API
  
 
== Use Cases ==
 
== Use Cases ==
 
These are some of the use cases borrowed from the W3 WADL specification.
 
These are some of the use cases borrowed from the W3 WADL specification.
 +
 
* Application Modelling and Visualization
 
* Application Modelling and Visualization
 
** Support for development of resource modelling tools for resource relationship and choreography analysis and manipulation.
 
** Support for development of resource modelling tools for resource relationship and choreography analysis and manipulation.
Line 31: Line 32:
  
 
== Implementation Overview ==
 
== Implementation Overview ==
Write a python script in quantum/tools/wadl/generate_wadl.py
+
Write a python script ''quantum/tools/wadl/generate_docs.sh'' and ''quantum/tools/wadl/extract_attrs.py''
* Traverse modules in quantum.api and quantum.extension and finds RESOURCE_ATTRIBUTE_MAP definitions in each module.
+
 
* Automatically generate WADL documents (core.wadl, [extention].wadl, etc.) files in quantum/doc/wadl/
+
* Process core APIs
** All '''param''' components will be populated according to the RESOURCE_ATTRIBUTE_MAP dictionary
+
** Retrieve the RESOURCE_ATTR_MAP in quantum.api.v2.attributes
 +
** Create document quantum/doc/wadl/core.wadl based on the RESOURCE_ATTR_MAP dict.
 +
* Process API extensions
 +
** Traverse modules in quantum/quantum/extension and find all subclasses of quantum.extension.[[ExtensionDescriptor]] in each module.
 +
** Retrieve the attr_map property in each [[ResourceExtension]] object returned by the get_resources() method of  [[ExtensionDescriptior]].
 +
** Automatically generate WADL document files
 +
*** quantum/doc/wadl/[extention].wadl
 +
* All data will be populated according to the attr_map for each API extension module
  
 
== Data Model Changes ==
 
== Data Model Changes ==
Line 61: Line 69:
  
 
== Usage Example ==
 
== Usage Example ==
: [How to run/use/interface with the new feature. (If applicable)]
+
After changing the core API or API extension specification in the source code, the developer will run ''./tools/wadl/generate_docs.sh'' to update the WADL documents in ''quantum/doc/wadl/''
  
 
== Test Cases ==
 
== Test Cases ==
: [Description of various test cases. (If applicable)]
+
No plans of test cases. However need to check if all API extensions are subclassing from quantum.extension.[[ExtensionDescriptor]] beforehand.

Latest revision as of 15:54, 21 June 2013

Quantum API WADL Specification

blueprint link

Resources

Scope

Provide WADL documents for the Quantum core API and API extensions.

WADL document scope

  • Core APIs will have a WADL document
  • All extension APIs will have its own WADL document
  • Each WADL document will have one application component
  • An application component will have one resources component
  • A resources component will have resource components for each resource entity
    • eg) network, subnet, port, etc.
  • Each resource component will have method components for GET(list, show), POST(create, bulk create), PUT(update), and DELETE(delete).
  • Each method component will have a request component and a optional response component
  • A request or response component will have representation components composed with param components based on the attribute resource map of the API

Use Cases

These are some of the use cases borrowed from the W3 WADL specification.

  • Application Modelling and Visualization
    • Support for development of resource modelling tools for resource relationship and choreography analysis and manipulation.
  • Code Generation
    • Automated generation of stub and skeleton code and code for manipulation of resource representations.
  • Configuration
    • Configuration of client and server using a portable format.

Implementation Overview

Write a python script quantum/tools/wadl/generate_docs.sh and quantum/tools/wadl/extract_attrs.py

  • Process core APIs
    • Retrieve the RESOURCE_ATTR_MAP in quantum.api.v2.attributes
    • Create document quantum/doc/wadl/core.wadl based on the RESOURCE_ATTR_MAP dict.
  • Process API extensions
    • Traverse modules in quantum/quantum/extension and find all subclasses of quantum.extension.ExtensionDescriptor in each module.
    • Retrieve the attr_map property in each ResourceExtension object returned by the get_resources() method of ExtensionDescriptior.
    • Automatically generate WADL document files
      • quantum/doc/wadl/[extention].wadl
  • All data will be populated according to the attr_map for each API extension module

Data Model Changes

N/A

Configuration variables

N/A

API's

N/A

Plugin Interface

N/A

Required Plugin support

N/A

Dependencies

None

CLI Requirements

N/A

Horizon Requirements

N/A

Usage Example

After changing the core API or API extension specification in the source code, the developer will run ./tools/wadl/generate_docs.sh to update the WADL documents in quantum/doc/wadl/

Test Cases

No plans of test cases. However need to check if all API extensions are subclassing from quantum.extension.ExtensionDescriptor beforehand.