2 This work is licensed under a Creative Commons Attribution 4.0
5 ====================================
6 Elastic API exposure for Multi Cloud
7 ====================================
9 This spec is to provide a framework for Multi-Cloud to expose API.
14 Multi-Cloud provides VIM API for other projects in ONAP. API will vary for
15 different projects. However, Multi-Cloud exposes its API by static code.
16 Current way of API exposing produces code duplications.
18 #. When a client creates a resource through Multi-Cloud, Multi-Cloud needs
19 to convert the API request to back-end OpenStack API request and send to
20 OpenStack. When a client requests a resource through Multi-Cloud, Multi-Cloud
21 needs to retrieve OpenStack resource, converts to its API and reply to client.
22 Even though the two conversion are the same thing with different directions,
23 there are 2 sets of code for it.
25 #. Most of Multi-Cloud API shares same logic. But the code of this same logic
26 are duplicated for every API.
28 Given the fact mentioned above, current code amount of Multi-Cloud are larger
29 than it should be. It makes code maintaining be time-consuming and error-prone.
31 Besides, the swagger files that describe API of Multi-Cloud are maintained
32 manually. It is thousands lines of code and hard for developers to maintain.
37 This spec proposes using YAML files to describe Multi-Cloud API. A framework
38 will also be provided. When Multi-Cloud services start up, the framework will
39 read YAML files, parse them and generate API accordingly. Multi-Cloud can
40 dynamically expose API in this way without changing its Python code. And
41 developers only need to maintain YAML files that describe Multi-Cloud API.
42 The YAML files are expected to be less amount than current way of API exposing,
43 because it only contains metadata of Multi-Cloud API.
45 Using the proposal in this spec, metadata of API are defined in YAML files and
46 logic of API handling are concentrated in the framework mentioned above. So
47 that the code duplication can be eliminated.
49 To narrow down the scope of this spec, none of current Multi-Cloud API will be
50 changed. This spec will ONLY focus on migrating Multi-Cloud API from current
51 way to the proposed framework in this spec. However, migrating all API to the
52 proposed framework is out of the scope of this spec. A set of API for one
53 specific use case, for example VoLTE, will be migrated to proposed framework.
54 Migrating all API can be implemented in other workitem(s) in future.
56 To narrow down the scope of this spec, a full, normative definition of API and
57 resources will not be considered. Only partial API will be considered. But it
58 can be implemented in other workitem(s) in future.
60 To narrow down the scope of this spec, only the functionality that Multi-Cloud
61 has now will be considered and extension support will not be considered in this
62 spec. But it can be implemented in other workitem(s) in future.
64 It should be noted that, though this spec focuses on how to convert northbound
65 and southboud API, it doesn't prevent tieing northbound API of MultCloud with
66 other functionalities. In setion `Definition of API`, an example of API
67 definition has been given, developer can add specific code/module path as a
68 attribute(like `handler`) under `path`, instead of defining `vim_path`. By
69 doing that, developer can tie the northbound API with specific code/module,
70 and expose northbound API with any functionality. This spec just shows
71 the capability of doing this by using the elastic API exposure framework, the
72 implementation for now will still focus on the northbound and southboud API
75 It should be noted that there is a prior art in OpenStack "Gluon" [1]_ project
76 which provides a model-driven framework to generate APIs based on model
78 in YAML. A full, normative definition and extension mechanism of "API
80 [2]_ is available in Gluon. Although our current work has limited scope, for
82 who are interested in full normative definition and extension mechanism in our
84 work, please refer to those references in "Gluon" [1]_ project and its "API
87 .. [1] https://wiki.openstack.org/wiki/Gluon
88 .. [2] https://github.com/openstack/gluon/blob/master/doc/source/devref/gluon_api_spec.inc
90 Since the API are defined by YAML files, swagger files can also be generated
91 from YAML files and exist without manually maintaining. The framework will
92 cover the conversion from YAML file to swagger files.
94 To keep backward compatibility, the proposal in this spec will be bound to
96 This means that the proposal is only usable when evenlet with pecan is
97 enabled. So that uses don't care about this feature will not be affected.
99 .. [MULTICLOUD-150] https://jira.onap.org/browse/MULTICLOUD-150
105 Take the API of `host` as example. The API will be defined as follow. URLs of
106 the API are defined under `paths`. There are several attributes for the API.
107 The number of kinds of attributes is not constrained to following example,
108 other attributes can be added if needed.
113 /{vimid}/{tenantid}/hosts/{hostid}:
127 description: content of host
129 vim_path: {nova_endpoint}/os-hypervisors
134 `parameters` are the variables in the URL. It can be extracted from URL and
135 then used in data retrieving and manipulating.
137 `parameters` are discriminated by `name`, and validated by `type` and `format`.
139 post, put, get, delete
140 ~~~~~~~~~~~~~~~~~~~~~~
142 These attributes represents the supported HTTP method. In above example, only
143 `get` method is defined. When client sends other HTTP method to the URL, a 404
144 response will be returned.
146 `responses` defines the response of the request. `success_code` is the HTTP
147 code in the response. `description` is an optional parameter. It describes the
149 `schema` points to the RESTful resource that will be in the response body. In
150 above example, the RESTful resource is `host`. It should be found in the
151 RESTful resource definition section.
156 `vim_path` defines the relative URL path of the southbound VIM. Multi-Cloud
157 will use this path to retrieve data from VIM.
159 Definition of RESTful resource
160 ------------------------------
162 Take the resource `host` as example. The resource will be defined as follow.
163 Resources are defined under `definitions`. The are several attributes for the
164 resource. The number of kinds of attributes is not constrained to following
165 example, other attributes can be added if needed.
171 vim_resource: hypervisor
176 source: hypervisor.name
180 source: hypervisor.vcpus
186 source: hypervisor.local_disk_size
191 source: hypervisor.memory_size
197 `vim_resource` points to the resource that comes from southbound VIM.
198 Multi-Cloud will use the resource to build its own resource.
203 `properties` defines the properties of the resource. Each property has a name
204 and several attributes. The number of kinds of attributes is not constrained
205 to the example, other attributes can be added if needed.
207 `type` of property means the type of current property. It can be some simple
209 like string or integer. It can also be some composite data like, object or
212 `required` of property means if this property is required for the resource. If
213 it is required, missing this property will cause request failure. Default value
214 of `required` is false.
216 `source` of property means that current property will be built from it. It is
217 usually a property from `vim_resource`. By default, it will be the same
218 property in `vim_resource`.
220 `action` of property means that current property will be build by using this
222 By default, it will be `copy`, which means the data from property of VIM
224 is copied to property of Multi-Cloud resource. Other actions can be defined for
227 `minimal` is one of the constraint of the property. It means the minimal
229 value of the property. If value of the property is less than minimal value. The
232 Swagger File generation
233 -----------------------
235 Multi-Cloud is using Swagger file to describe its API. It is maintained
237 Since this spec proposes to use YAML file to generate Multi-Cloud's API,
239 file can also be generated from YAML file. The API generating framework will
241 generate Swagger file.
249 #. Add YAML parser for API and resource.
250 #. Add REST client to call southbound VIM API.
251 #. Add validator for resource.
252 #. Add action for resouce.
253 #. Add Swagger file generator.
254 #. Migrate /{vimid}/{tenantid}/hosts/{hostid} as an example.