Update API doc

[multicloud/framework.git] / docs / specs / elastic_api_exposure.rst

diff --git a/docs/specs/elastic_api_exposure.rst b/docs/specs/elastic_api_exposure.rst
index 4cea241..99061d7 100644 (file)
--- a/docs/specs/elastic_api_exposure.rst
+++ b/docs/specs/elastic_api_exposure.rst
@@ -73,10 +73,14 @@ implementation for now will still focus on the northbound and southboud API
 conversion.
 
 It should be noted that there is a prior art in OpenStack "Gluon" [1]_ project
 conversion.
 
 It should be noted that there is a prior art in OpenStack "Gluon" [1]_ project

-which provides a model-driven framework to generate APIs based on model definitions
-in YAML. A full, normative definition and extension mechanism of "API Specification"
-[2]_ is available in Gluon. Although our current work has limited scope, for those
-who are interested in full normative definition and extension mechanism in our future
+which provides a model-driven framework to generate APIs based on model
+definitions
+in YAML. A full, normative definition and extension mechanism of "API
+Specification"
+[2]_ is available in Gluon. Although our current work has limited scope, for
+those
+who are interested in full normative definition and extension mechanism in our
+future

 work, please refer to those references in "Gluon" [1]_ project and its "API
 Specifications" [2]_.
 
 work, please refer to those references in "Gluon" [1]_ project and its "API
 Specifications" [2]_.
 


@@ -84,10 +88,11 @@ Specifications" [2]_.
 .. [2] https://github.com/openstack/gluon/blob/master/doc/source/devref/gluon_api_spec.inc
 
 Since the API are defined by YAML files, swagger files can also be generated
 .. [2] https://github.com/openstack/gluon/blob/master/doc/source/devref/gluon_api_spec.inc
 
 Since the API are defined by YAML files, swagger files can also be generated

-from YAML files and exist without manually maintaining. The framework will cover
-the conversion from YAML file to swagger files.
+from YAML files and exist without manually maintaining. The framework will
+cover the conversion from YAML file to swagger files.

 
 

-To keep backward compatibility, the proposal in this spec will be bound to [MULTICLOUD-150]_.
+To keep backward compatibility, the proposal in this spec will be bound to
+[MULTICLOUD-150]_.

 This means that the proposal is only usable when evenlet with pecan is
 enabled. So that uses don't care about this feature will not be affected.
 
 This means that the proposal is only usable when evenlet with pecan is
 enabled. So that uses don't care about this feature will not be affected.
 


@@ -98,9 +103,9 @@ Definition of API
 -----------------
 
 Take the API of `host` as example. The API will be defined as follow. URLs of
 -----------------
 
 Take the API of `host` as example. The API will be defined as follow. URLs of

-the API are defined under `paths`. There are several attributes for the API. The
-number of kinds of attributes is not constrained to following example, other
-attributes can be added if needed.
+the API are defined under `paths`. There are several attributes for the API.
+The number of kinds of attributes is not constrained to following example,
+other attributes can be added if needed.

 
 ::
 
 
 ::
 


@@ -126,8 +131,8 @@ attributes can be added if needed.
 parameters
 ~~~~~~~~~~
 
 parameters
 ~~~~~~~~~~
 

-`parameters` are the variables in the URL. It can be extracted from URL and then
-used in data retrieving and manipulating.
+`parameters` are the variables in the URL. It can be extracted from URL and
+then used in data retrieving and manipulating.

 
 `parameters` are discriminated by `name`, and validated by `type` and `format`.
 
 
 `parameters` are discriminated by `name`, and validated by `type` and `format`.
 


@@ -138,17 +143,18 @@ These attributes represents the supported HTTP method. In above example, only
 `get` method is defined. When client sends other HTTP method to the URL, a 404
 response will be returned.
 
 `get` method is defined. When client sends other HTTP method to the URL, a 404
 response will be returned.
 

-`responses` defines the response of the request. `success_code` is the HTTP code
-in the response. `description` is an optional parameter. It describes the response.
+`responses` defines the response of the request. `success_code` is the HTTP
+code in the response. `description` is an optional parameter. It describes the
+response.

 `schema` points to the RESTful resource that will be in the response body. In
 `schema` points to the RESTful resource that will be in the response body. In

-above example, the RESTful resource is `host`. It should be found in the RESTful
-resource definition section.
+above example, the RESTful resource is `host`. It should be found in the
+RESTful resource definition section.

 
 vim_path
 ~~~~~~~~
 
 
 vim_path
 ~~~~~~~~
 

-`vim_path` defines the relative URL path of the southbound VIM. Multi-Cloud will
-use this path to retrieve data from VIM.
+`vim_path` defines the relative URL path of the southbound VIM. Multi-Cloud
+will use this path to retrieve data from VIM.

 
 Definition of RESTful resource
 ------------------------------
 
 Definition of RESTful resource
 ------------------------------


@@ -188,8 +194,8 @@ example, other attributes can be added if needed.
 vim_resource
 ~~~~~~~~~~~~
 
 vim_resource
 ~~~~~~~~~~~~
 

-`vim_resource` points to the resource that comes from southbound VIM. Multi-Cloud
-will use the resource to build its own resource.
+`vim_resource` points to the resource that comes from southbound VIM.
+Multi-Cloud will use the resource to build its own resource.

 
 properties
 ~~~~~~~~~~
 
 properties
 ~~~~~~~~~~


@@ -198,32 +204,40 @@ properties
 and several attributes. The number of kinds of attributes is not constrained
 to the example, other attributes can be added if needed.
 
 and several attributes. The number of kinds of attributes is not constrained
 to the example, other attributes can be added if needed.
 

-`type` of property means the type of current property. It can be some simple data,
-like string or integer. It can also be some composite data like, object or array.
+`type` of property means the type of current property. It can be some simple
+data,
+like string or integer. It can also be some composite data like, object or
+array.

 
 

-`required` of property means if this property is required for the resource. If it
-is required, missing this property will cause request failure. Default value of
-`required` is false.
+`required` of property means if this property is required for the resource. If
+it is required, missing this property will cause request failure. Default value
+of `required` is false.

 
 `source` of property means that current property will be built from it. It is
 
 `source` of property means that current property will be built from it. It is

-usually a property from `vim_resource`. By default, it will be the same property
-in `vim_resource`.
+usually a property from `vim_resource`. By default, it will be the same
+property in `vim_resource`.

 
 

-`action` of property means that current property will be build by using this action.
-By default, it will be `copy`, which means the data from property of VIM resource
+`action` of property means that current property will be build by using this
+action.
+By default, it will be `copy`, which means the data from property of VIM
+resource

 is copied to property of Multi-Cloud resource. Other actions can be defined for
 different scenarios.
 
 is copied to property of Multi-Cloud resource. Other actions can be defined for
 different scenarios.
 

-`minimal` is one of the constraint of the property. It means the minimal possible
+`minimal` is one of the constraint of the property. It means the minimal
+possible

 value of the property. If value of the property is less than minimal value. The
 request will fail.
 
 Swagger File generation
 -----------------------
 
 value of the property. If value of the property is less than minimal value. The
 request will fail.
 
 Swagger File generation
 -----------------------
 

-Multi-Cloud is using Swagger file to describe its API. It is maintained manually.
-Since this spec proposes to use YAML file to generate Multi-Cloud's API, Swagger
-file can also be generated from YAML file. The API generating framework will also
+Multi-Cloud is using Swagger file to describe its API. It is maintained
+manually.
+Since this spec proposes to use YAML file to generate Multi-Cloud's API,
+Swagger
+file can also be generated from YAML file. The API generating framework will
+also

 generate Swagger file.
 
 Implementation
 generate Swagger file.
 
 Implementation