docs/specs/elastic_api_exposure.rst

   1 ..
   2  This work is licensed under a Creative Commons Attribution 4.0
   3  International License.
   4
   5 ====================================
   6 Elastic API exposure for Multi Cloud
   7 ====================================
   8
   9 This spec is to provide a framework for Multi-Cloud to expose API.
  10
  11 Problem Description
  12 ===================
  13
  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.
  17
  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.
  24
  25 #. Most of Multi-Cloud API shares same logic. But the code of this same logic
  26 are duplicated for every API.
  27
  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.
  30
  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.
  33
  34 Proposed Change
  35 ===============
  36
  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.
  44
  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.
  48
  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.
  55
  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.
  59
  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.
  63
  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
  73 conversion.
  74
  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
  77 definitions
  78 in YAML. A full, normative definition and extension mechanism of "API
  79 Specification"
  80 [2]_ is available in Gluon. Although our current work has limited scope, for
  81 those
  82 who are interested in full normative definition and extension mechanism in our
  83 future
  84 work, please refer to those references in "Gluon" [1]_ project and its "API
  85 Specifications" [2]_.
  86
  87 .. [1] https://wiki.openstack.org/wiki/Gluon
  88 .. [2] https://github.com/openstack/gluon/blob/master/doc/source/devref/gluon_api_spec.inc
  89
  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.
  93
  94 To keep backward compatibility, the proposal in this spec will be bound to
  95 [MULTICLOUD-150]_.
  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.
  98
  99 .. [MULTICLOUD-150] https://jira.onap.org/browse/MULTICLOUD-150
 100
 101
 102 Definition of API
 103 -----------------
 104
 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.
 109
 110 ::
 111
 112     paths:
 113       /{vimid}/{tenantid}/hosts/{hostid}:
 114         parameters:
 115           - type: string
 116             format: uuid
 117             name: vimid
 118           - type: string
 119             format: uuid
 120             name: tenantid
 121           - type: string
 122             format: uuid
 123             name: hostid
 124         get:
 125           responses:
 126             success_code: 200
 127             description: content of host
 128             schema: host
 129         vim_path: {nova_endpoint}/os-hypervisors
 130
 131 parameters
 132 ~~~~~~~~~~
 133
 134 `parameters` are the variables in the URL. It can be extracted from URL and
 135 then used in data retrieving and manipulating.
 136
 137 `parameters` are discriminated by `name`, and validated by `type` and `format`.
 138
 139 post, put, get, delete
 140 ~~~~~~~~~~~~~~~~~~~~~~
 141
 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.
 145
 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
 148 response.
 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.
 152
 153 vim_path
 154 ~~~~~~~~
 155
 156 `vim_path` defines the relative URL path of the southbound VIM. Multi-Cloud
 157 will use this path to retrieve data from VIM.
 158
 159 Definition of RESTful resource
 160 ------------------------------
 161
 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.
 166
 167 ::
 168
 169     definitions:
 170       host:
 171         vim_resource: hypervisor
 172         properties:
 173           name:
 174             type: string
 175             required: true
 176             source: hypervisor.name
 177           cpu:
 178             type: integer
 179             minimal: 1
 180             source: hypervisor.vcpus
 181             action: copy
 182             required: true
 183           disk_gb:
 184             type: integer
 185             minimal: 0
 186             source: hypervisor.local_disk_size
 187             required: true
 188           memory_mb:
 189             type: integer
 190             minimal: 0
 191             source: hypervisor.memory_size
 192             required: true
 193
 194 vim_resource
 195 ~~~~~~~~~~~~
 196
 197 `vim_resource` points to the resource that comes from southbound VIM.
 198 Multi-Cloud will use the resource to build its own resource.
 199
 200 properties
 201 ~~~~~~~~~~
 202
 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.
 206
 207 `type` of property means the type of current property. It can be some simple
 208 data,
 209 like string or integer. It can also be some composite data like, object or
 210 array.
 211
 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.
 215
 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`.
 219
 220 `action` of property means that current property will be build by using this
 221 action.
 222 By default, it will be `copy`, which means the data from property of VIM
 223 resource
 224 is copied to property of Multi-Cloud resource. Other actions can be defined for
 225 different scenarios.
 226
 227 `minimal` is one of the constraint of the property. It means the minimal
 228 possible
 229 value of the property. If value of the property is less than minimal value. The
 230 request will fail.
 231
 232 Swagger File generation
 233 -----------------------
 234
 235 Multi-Cloud is using Swagger file to describe its API. It is maintained
 236 manually.
 237 Since this spec proposes to use YAML file to generate Multi-Cloud's API,
 238 Swagger
 239 file can also be generated from YAML file. The API generating framework will
 240 also
 241 generate Swagger file.
 242
 243 Implementation
 244 ==============
 245
 246 Work Items
 247 ----------
 248
 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.