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 definitions
  77 in YAML. A full, normative definition and extension mechanism of "API Specification"
  78 [2]_ is available in Gluon. Although our current work has limited scope, for those
  79 who are interested in full normative definition and extension mechanism in our future
  80 work, please refer to those references in "Gluon" [1]_ project and its "API
  81 Specifications" [2]_.
  82
  83 .. [1] https://wiki.openstack.org/wiki/Gluon
  84 .. [2] https://github.com/openstack/gluon/blob/master/doc/source/devref/gluon_api_spec.inc
  85
  86 Since the API are defined by YAML files, swagger files can also be generated
  87 from YAML files and exist without manually maintaining. The framework will cover
  88 the conversion from YAML file to swagger files.
  89
  90 To keep backward compatibility, the proposal in this spec will be bound to [MULTICLOUD-150]_.
  91 This means that the proposal is only usable when evenlet with pecan is
  92 enabled. So that uses don't care about this feature will not be affected.
  93
  94 .. [MULTICLOUD-150] https://jira.onap.org/browse/MULTICLOUD-150
  95
  96
  97 Definition of API
  98 -----------------
  99
 100 Take the API of `host` as example. The API will be defined as follow. URLs of
 101 the API are defined under `paths`. There are several attributes for the API. The
 102 number of kinds of attributes is not constrained to following example, other
 103 attributes can be added if needed.
 104
 105 ::
 106
 107     paths:
 108       /{vimid}/{tenantid}/hosts/{hostid}:
 109         parameters:
 110           - type: string
 111             format: uuid
 112             name: vimid
 113           - type: string
 114             format: uuid
 115             name: tenantid
 116           - type: string
 117             format: uuid
 118             name: hostid
 119         get:
 120           responses:
 121             success_code: 200
 122             description: content of host
 123             schema: host
 124         vim_path: {nova_endpoint}/os-hypervisors
 125
 126 parameters
 127 ~~~~~~~~~~
 128
 129 `parameters` are the variables in the URL. It can be extracted from URL and then
 130 used in data retrieving and manipulating.
 131
 132 `parameters` are discriminated by `name`, and validated by `type` and `format`.
 133
 134 post, put, get, delete
 135 ~~~~~~~~~~~~~~~~~~~~~~
 136
 137 These attributes represents the supported HTTP method. In above example, only
 138 `get` method is defined. When client sends other HTTP method to the URL, a 404
 139 response will be returned.
 140
 141 `responses` defines the response of the request. `success_code` is the HTTP code
 142 in the response. `description` is an optional parameter. It describes the response.
 143 `schema` points to the RESTful resource that will be in the response body. In
 144 above example, the RESTful resource is `host`. It should be found in the RESTful
 145 resource definition section.
 146
 147 vim_path
 148 ~~~~~~~~
 149
 150 `vim_path` defines the relative URL path of the southbound VIM. Multi-Cloud will
 151 use this path to retrieve data from VIM.
 152
 153 Definition of RESTful resource
 154 ------------------------------
 155
 156 Take the resource `host` as example. The resource will be defined as follow.
 157 Resources are defined under `definitions`. The are several attributes for the
 158 resource. The number of kinds of attributes is not constrained to following
 159 example, other attributes can be added if needed.
 160
 161 ::
 162
 163     definitions:
 164       host:
 165         vim_resource: hypervisor
 166         properties:
 167           name:
 168             type: string
 169             required: true
 170             source: hypervisor.name
 171           cpu:
 172             type: integer
 173             minimal: 1
 174             source: hypervisor.vcpus
 175             action: copy
 176             required: true
 177           disk_gb:
 178             type: integer
 179             minimal: 0
 180             source: hypervisor.local_disk_size
 181             required: true
 182           memory_mb:
 183             type: integer
 184             minimal: 0
 185             source: hypervisor.memory_size
 186             required: true
 187
 188 vim_resource
 189 ~~~~~~~~~~~~
 190
 191 `vim_resource` points to the resource that comes from southbound VIM. Multi-Cloud
 192 will use the resource to build its own resource.
 193
 194 properties
 195 ~~~~~~~~~~
 196
 197 `properties` defines the properties of the resource. Each property has a name
 198 and several attributes. The number of kinds of attributes is not constrained
 199 to the example, other attributes can be added if needed.
 200
 201 `type` of property means the type of current property. It can be some simple data,
 202 like string or integer. It can also be some composite data like, object or array.
 203
 204 `required` of property means if this property is required for the resource. If it
 205 is required, missing this property will cause request failure. Default value of
 206 `required` is false.
 207
 208 `source` of property means that current property will be built from it. It is
 209 usually a property from `vim_resource`. By default, it will be the same property
 210 in `vim_resource`.
 211
 212 `action` of property means that current property will be build by using this action.
 213 By default, it will be `copy`, which means the data from property of VIM resource
 214 is copied to property of Multi-Cloud resource. Other actions can be defined for
 215 different scenarios.
 216
 217 `minimal` is one of the constraint of the property. It means the minimal possible
 218 value of the property. If value of the property is less than minimal value. The
 219 request will fail.
 220
 221 Swagger File generation
 222 -----------------------
 223
 224 Multi-Cloud is using Swagger file to describe its API. It is maintained manually.
 225 Since this spec proposes to use YAML file to generate Multi-Cloud's API, Swagger
 226 file can also be generated from YAML file. The API generating framework will also
 227 generate Swagger file.
 228
 229 Implementation
 230 ==============
 231
 232 Work Items
 233 ----------
 234
 235 #. Add YAML parser for API and resource.
 236 #. Add REST client to call southbound VIM API.
 237 #. Add validator for resource.
 238 #. Add action for resouce.
 239 #. Add Swagger file generator.
 240 #. Migrate /{vimid}/{tenantid}/hosts/{hostid} as an example.