docs/specs/elastic_api_exposure.rst

   1 ..
   2  This work is licensed under a Creative Commons Attribution 4.0
   3  International License.
   4 .. _offeredapis:
   5
   6 ====================================
   7 Elastic API exposure for Multi Cloud
   8 ====================================
   9
  10 This spec is to provide a framework for Multi-Cloud to expose API.
  11
  12 Problem Description
  13 ===================
  14
  15 Multi-Cloud provides VIM API for other projects in ONAP. API will vary for
  16 different projects. However, Multi-Cloud exposes its API by static code.
  17 Current way of API exposing produces code duplications.
  18
  19 #. When a client creates a resource through Multi-Cloud, Multi-Cloud needs
  20 to convert the API request to back-end OpenStack API request and send to
  21 OpenStack. When a client requests a resource through Multi-Cloud, Multi-Cloud
  22 needs to retrieve OpenStack resource, converts to its API and reply to client.
  23 Even though the two conversion are the same thing with different directions,
  24 there are 2 sets of code for it.
  25
  26 #. Most of Multi-Cloud API shares same logic. But the code of this same logic
  27 are duplicated for every API.
  28
  29 Given the fact mentioned above, current code amount of Multi-Cloud are larger
  30 than it should be. It makes code maintaining be time-consuming and error-prone.
  31
  32 Besides, the swagger files that describe API of Multi-Cloud are maintained
  33 manually. It is thousands lines of code and hard for developers to maintain.
  34
  35 Proposed Change
  36 ===============
  37
  38 This spec proposes using YAML files to describe Multi-Cloud API. A framework
  39 will also be provided. When Multi-Cloud services start up, the framework will
  40 read YAML files, parse them and generate API accordingly. Multi-Cloud can
  41 dynamically expose API in this way without changing its Python code. And
  42 developers only need to maintain YAML files that describe Multi-Cloud API.
  43 The YAML files are expected to be less amount than current way of API exposing,
  44 because it only contains metadata of Multi-Cloud API.
  45
  46 Using the proposal in this spec, metadata of API are defined in YAML files and
  47 logic of API handling are concentrated in the framework mentioned above. So
  48 that the code duplication can be eliminated.
  49
  50 To narrow down the scope of this spec, none of current Multi-Cloud API will be
  51 changed. This spec will ONLY focus on migrating Multi-Cloud API from current
  52 way to the proposed framework in this spec. However, migrating all API to the
  53 proposed framework is out of the scope of this spec. A set of API for one
  54 specific use case, for example VoLTE, will be migrated to proposed framework.
  55 Migrating all API can be implemented in other workitem(s) in future.
  56
  57 To narrow down the scope of this spec, a full, normative definition of API and
  58 resources will not be considered. Only partial API will be considered. But it
  59 can be implemented in other workitem(s) in future.
  60
  61 To narrow down the scope of this spec, only the functionality that Multi-Cloud
  62 has now will be considered and extension support will not be considered in this
  63 spec. But it can be implemented in other workitem(s) in future.
  64
  65 It should be noted that, though this spec focuses on how to convert northbound
  66 and southboud API, it doesn't prevent tieing northbound API of MultCloud with
  67 other functionalities. In setion `Definition of API`, an example of API
  68 definition has been given, developer can add specific code/module path as a
  69 attribute(like `handler`) under `path`, instead of defining `vim_path`. By
  70 doing that, developer can tie the northbound API with specific code/module,
  71 and expose northbound API with any functionality. This spec just shows
  72 the capability of doing this by using the elastic API exposure framework, the
  73 implementation for now will still focus on the northbound and southboud API
  74 conversion.
  75
  76 It should be noted that there is a prior art in OpenStack "Gluon" [1]_ project
  77 which provides a model-driven framework to generate APIs based on model
  78 definitions
  79 in YAML. A full, normative definition and extension mechanism of "API
  80 Specification"
  81 [2]_ is available in Gluon. Although our current work has limited scope, for
  82 those
  83 who are interested in full normative definition and extension mechanism in our
  84 future
  85 work, please refer to those references in "Gluon" [1]_ project and its "API
  86 Specifications" [2]_.
  87
  88 .. [1] https://wiki.openstack.org/wiki/Gluon
  89 .. [2] https://github.com/openstack/gluon/blob/master/doc/source/devref/gluon_api_spec.inc
  90
  91 Since the API are defined by YAML files, swagger files can also be generated
  92 from YAML files and exist without manually maintaining. The framework will
  93 cover the conversion from YAML file to swagger files.
  94
  95 To keep backward compatibility, the proposal in this spec will be bound to
  96 [MULTICLOUD-150]_.
  97 This means that the proposal is only usable when evenlet with pecan is
  98 enabled. So that uses don't care about this feature will not be affected.
  99
 100 .. [MULTICLOUD-150] https://jira.onap.org/browse/MULTICLOUD-150
 101
 102
 103 Definition of API
 104 -----------------
 105
 106 Take the API of `host` as example. The API will be defined as follow. URLs of
 107 the API are defined under `paths`. There are several attributes for the API.
 108 The number of kinds of attributes is not constrained to following example,
 109 other attributes can be added if needed.
 110
 111 ::
 112
 113     paths:
 114       /{vimid}/{tenantid}/hosts/{hostid}:
 115         parameters:
 116           - type: string
 117             format: uuid
 118             name: vimid
 119           - type: string
 120             format: uuid
 121             name: tenantid
 122           - type: string
 123             format: uuid
 124             name: hostid
 125         get:
 126           responses:
 127             success_code: 200
 128             description: content of host
 129             schema: host
 130         vim_path: {nova_endpoint}/os-hypervisors
 131
 132 parameters
 133 ~~~~~~~~~~
 134
 135 `parameters` are the variables in the URL. It can be extracted from URL and
 136 then used in data retrieving and manipulating.
 137
 138 `parameters` are discriminated by `name`, and validated by `type` and `format`.
 139
 140 post, put, get, delete
 141 ~~~~~~~~~~~~~~~~~~~~~~
 142
 143 These attributes represents the supported HTTP method. In above example, only
 144 `get` method is defined. When client sends other HTTP method to the URL, a 404
 145 response will be returned.
 146
 147 `responses` defines the response of the request. `success_code` is the HTTP
 148 code in the response. `description` is an optional parameter. It describes the
 149 response.
 150 `schema` points to the RESTful resource that will be in the response body. In
 151 above example, the RESTful resource is `host`. It should be found in the
 152 RESTful resource definition section.
 153
 154 vim_path
 155 ~~~~~~~~
 156
 157 `vim_path` defines the relative URL path of the southbound VIM. Multi-Cloud
 158 will use this path to retrieve data from VIM.
 159
 160 Definition of RESTful resource
 161 ------------------------------
 162
 163 Take the resource `host` as example. The resource will be defined as follow.
 164 Resources are defined under `definitions`. The are several attributes for the
 165 resource. The number of kinds of attributes is not constrained to following
 166 example, other attributes can be added if needed.
 167
 168 ::
 169
 170     definitions:
 171       host:
 172         vim_resource: hypervisor
 173         properties:
 174           name:
 175             type: string
 176             required: true
 177             source: hypervisor.name
 178           cpu:
 179             type: integer
 180             minimal: 1
 181             source: hypervisor.vcpus
 182             action: copy
 183             required: true
 184           disk_gb:
 185             type: integer
 186             minimal: 0
 187             source: hypervisor.local_disk_size
 188             required: true
 189           memory_mb:
 190             type: integer
 191             minimal: 0
 192             source: hypervisor.memory_size
 193             required: true
 194
 195 vim_resource
 196 ~~~~~~~~~~~~
 197
 198 `vim_resource` points to the resource that comes from southbound VIM.
 199 Multi-Cloud will use the resource to build its own resource.
 200
 201 properties
 202 ~~~~~~~~~~
 203
 204 `properties` defines the properties of the resource. Each property has a name
 205 and several attributes. The number of kinds of attributes is not constrained
 206 to the example, other attributes can be added if needed.
 207
 208 `type` of property means the type of current property. It can be some simple
 209 data,
 210 like string or integer. It can also be some composite data like, object or
 211 array.
 212
 213 `required` of property means if this property is required for the resource. If
 214 it is required, missing this property will cause request failure. Default value
 215 of `required` is false.
 216
 217 `source` of property means that current property will be built from it. It is
 218 usually a property from `vim_resource`. By default, it will be the same
 219 property in `vim_resource`.
 220
 221 `action` of property means that current property will be build by using this
 222 action.
 223 By default, it will be `copy`, which means the data from property of VIM
 224 resource
 225 is copied to property of Multi-Cloud resource. Other actions can be defined for
 226 different scenarios.
 227
 228 `minimal` is one of the constraint of the property. It means the minimal
 229 possible
 230 value of the property. If value of the property is less than minimal value. The
 231 request will fail.
 232
 233 Swagger File generation
 234 -----------------------
 235
 236 Multi-Cloud is using Swagger file to describe its API. It is maintained
 237 manually.
 238 Since this spec proposes to use YAML file to generate Multi-Cloud's API,
 239 Swagger
 240 file can also be generated from YAML file. The API generating framework will
 241 also
 242 generate Swagger file.
 243
 244 Implementation
 245 ==============
 246
 247 Work Items
 248 ----------
 249
 250 #. Add YAML parser for API and resource.
 251 #. Add REST client to call southbound VIM API.
 252 #. Add validator for resource.
 253 #. Add action for resouce.
 254 #. Add Swagger file generator.
 255 #. Migrate /{vimid}/{tenantid}/hosts/{hostid} as an example.