Nova API Microversioning

  1. Overview

As the same with other OpenStack core projects, Nova also provides the communication via its REST APIs. However, current Nova API (v2) contains problems of input validation lacking, inconsistent interfaces and difficult to add a new API implementation, etc. To solve these problems, a new version of REST API called "v2.1" was exposed in Juno and being developed in coming OpenStack releases. This new approach will fulfil the term of decentralized API.

  1. The user perspectives:

  1. Use cases:

Arcording to the OpenStack official website (source: http://specs.openstack.org/openstack/nova-specs/specs/kilo/implemented/api-microversions.html):

 

  1. What is Nova API 2.1

Definition:

Nova v2.1 API = v2 compatibility + Validition + Microversioning

V2 Compatibility:

Validation:

Microversioning:

Versioning of the API should be a single monotonic counter. It will be of the form X.Y where it follows the following convention :

X will only be changed if a significant backwards incompatible API change is made which affects the API as whole. That is, something that is only very rarely incremented.

Y when you make any change to the API. Note that this includes semantic changes which may not affect the input or output formats or even originate in the API code layer. We are not distinguishing between backwards compatible and backwards incompatible changes in the versioning system. It will however be made clear in the documentation as to what is a backwards compatible change and what is a backwards incompatible one.

* 2.1 - Initial version. Equivalent to v2.0 code

* 2.2 - Adds (keypair) type parameter for os-keypairs plugin

           Fixes success status code for create/delete a keypair method

* 2.3 - Exposes additional os-extended-server-attributes

           Exposes delete_on_termination for os-extended-volumes

* 2.4 - Exposes reserved field in os-fixed-ips.

* 2.5 - Allow server search option ip6 for non-admin

* 2.6 - Consolidate the APIs for getting remote consoles

</blockquote>

  • Let’s check the API in request and response in Kilo version:

$ nova --debug –service-type computev21 list

DEBUG (session:195) REQ: curl -g -i -X GET http://192.168.50.20:8774/v2.1/87e5126a1c9a4db28482af97450a2e98/servers/detail -H "User-Agent: python-novaclient" -H "Accept: application/json" -H "X-Auth-Token: {SHA1}1c0e19248ad9acf77edddfc7b35cb806533799b0"

INFO (connectionpool:203) Starting new HTTP connection (1): 192.168.50.20

DEBUG (connectionpool:383) "GET /v2.1/87e5126a1c9a4db28482af97450a2e98/servers/detail HTTP/1.1" 200 15

DEBUG (session:224) RESP: [200] content-length: 15 x-compute-request-id: req-8d14500c-13a7-4a87-9db7-f5d9095393da vary: X-OpenStack-Nova-API-Version connection: keep-alive x-openstack-nova-api-version: 2.1 date: Thu, 16 Jul 2015 11:51:35 GMT content-type: application/json

</blockquote>

  • Client would specify the range of microversion in the “Accept” header. If it is not defined, the default value is v2.1. Then server would response with the version range that it can comply with. If not, the default value is v2.1

  • v3 becomes a global microversion of v2.2 (because of backwards incompatible changes).

  1. API Microversioning in Kilo:

  • With nova command now, there is no way to use microversion because microversion is not supported now in nova-pythonclient.

  • With APP/SDK: Specify a microversion in the request header:

                                    X-OpenStack-Nova-API-Version

  • If we pass with the “lastest”, Nova will take the maximum version of API. On each request the “X-OpenStack-Nova-API-Version” header string will be converted to an APIVersionRequest object in the “nova/api/openstack/wsgi.py” code.

  • If a user does not specify a version, they will get the “DEFAULT_API_VERSION” defined in “nova/api/openstack/wsgi.py”.

  • In the class controller of “nova/api/openstack/wsgi.py”, we define a decorator “api_version” for the methods. If you want to use “api_version” for some method, you should decorate it by “@wsgi.Controller.api_version”.

  • The validation schemas are put into the “/nova/api/openstack/compute/schemas”. These schemas will check the API version of request object.

 

Changes in code of Kilo:

  • In the /nova/api/openstack directory, there are two new files named “api_version_request.py” and ”versioned_method.py”

  • “api_version_request.py”:

    • Create an APIversionRequest object.

    • APIversionRequest object will be passed into the “api_version” decorator in Controller class of wsgi.py.

                In the /nova/api/openstack/wsgi.py:

               @classmethod

               def api_version:

    • This “api_version” decorator is added to the any method that takes the request object as the first parameter and this method belongs to a class that inherits from wsgi.Controller().

  • “versioned_method.py”:

    • Versioning information for a single method

    • It will return an object that has the name of method, min_api, max_api and the method.

 

  1. API Microversioning in Liberty:

  • The v2 will be replaced by v2.1

  • In long-term, v2 will be removed totally to reduce the maintenance most.

17/07/2015

VietStack team