openstack/nova
Code Issues Proposed changes

Improve stable-api doc with current API state

Browse Source 
extensions, stevedore and extensions config options are gone
and plain router is introduced in Pike.

Also this documents was little bit confusing about current and
old state of APIs.

This commit makes it more clear and reflect the current API state
and also describe the evolution of APIs.

Change-Id: I6522100a78241400b1ea059a39a32c259fe6ab90
This commit is contained in:
ghanshyam 2017-08-02 11:33:21 +03:00 committed by Ghanshyam Mann
parent f17feb558c
commit a03c667109
2 changed files with 84 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
doc/source/_static/images/evolution-of-api.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 30 KiB

117
doc/source/reference/stable-api.rst
View File

@ -19,66 +19,117 @@ Nova Stable REST API
====================
This document describes both the current state of the Nova REST API -- as
of the Newton release -- and also attempts to describe how the Nova team intends
to evolve the REST API's implementation over time and remove some of the
of the Pike release -- and also attempts to describe how the Nova team
evolved the REST API's implementation over time and remove some of the
cruft that has crept in over the years.
Background
----------
Nova used to include two distinct frameworks for exposing REST API
functionality. Older code is called the "V2 API" and existed in the
functionality. Older code is called the "v2 API" and existed in the
/nova/api/openstack/compute/legacy_v2/ directory. This code tree was totally
removed during Netwon release time frame (14.0.0 and later).
Newer code is called the "v2.1 API" and exists in the
Newer code is called the "v2.1 API" and exists in the
/nova/api/openstack/compute directory.
The V2 API is the old Nova REST API. It is mostly replaced by V2.1 API.
The v2 API is the old Nova REST API. It is mostly replaced by v2.1 API.
The V2.1 API is the new Nova REST API with a set of improvements which
The v2.1 API is the new Nova REST API with a set of improvements which
includes Microversion and standardized validation of inputs using JSON-Schema.
Also the V2.1 API is totally backwards compatible with the V2 API (That is the
reason we call it as V2.1 API).
Also the v2.1 API is totally backwards compatible with the v2 API (That is the
reason we call it as v2.1 API).
Stable API
----------
Current Stable API
------------------
In the V2 API, there is a concept called 'extension'. An operator can use it
to enable/disable part of Nova REST API based on requirements. An end user
may query the '/extensions' API to discover what *API functionality* is
* Nova v2.1 API + Microversion (v2.1 APIs are backward-compatible with
v2 API, but more strict validation)
* /v2 & /v2.1 endpoint supported
* v2 compatible mode for old v2 users
Evolution of Nova REST API
--------------------------
.. image:: /_static/images/evolution-of-api.png
Nova v2 API + Extensions
************************
Nova use to have v2 API. In v2 API, there was a concept called 'extension'.
An operator can use it to enable/disable part of Nova REST API based on requirements.
An end user may query the '/extensions' API to discover what *API functionality* is
supported by the Nova deployment.
Unfortunately, because V2 API extensions could be enabled or disabled
Unfortunately, because v2 API extensions could be enabled or disabled
from one deployment to another -- as well as custom API extensions added
to one deployment and not another -- it was impossible for an end user to
know what the OpenStack Compute API actually included. No two OpenStack
deployments were consistent, which made cloud interoperability impossible.
API extensions, being removed from the v2.1 API, are no longer
In Newton release, extensions magic was deprecated and marked for removal.
In Newton release, v2 API code base has been removed and /v2 endpoints were
directed to v2.1 code base.
v2 API compatibility mode based on v2.1 API
*******************************************
v2.1 API is exactly same as v2 API except strong input validation with no additional
request parameter allowed and Microversion feature.
Since Newton, '/v2' endpoint also started using v2.1 API implementation. But to keep the
backward compatibility of v2 API, '/v2' endpoint should not return error on additional
request parameter or any new headers for Microversion. v2 API must be same as it has
been since starting.
To achieve that behavior legacy v2 compatibility mode has been introduced. v2 compatibility
mode is based on v2.1 implementation with below difference:
* Skip additionalProperties checks in request body
* Ignore Microversion headers in request
* No Microversion headers in response
Nova v2.1 API + Microversion
****************************
In Kilo release, nova v2.1 API has been released. v2.1 API
is supposed to be backward compatible with v2 API with strong
input validation using JSON Schema.
v2.1 API comes up with microversion concept which is a way to version
the API changes. Each new feature or modification in API has to done
via microversion bump.
API extensions concept was deprecated from the v2.1 API, are no longer
needed to evolve the REST API, and no new API functionality should use
the API extension classes to implement new functionality. Instead, new
API functionality should use the microversioning decorators to add or change
the REST API.
API functionality should be added via microversion concept and use the
microversioning decorators to add or change the REST API.
The extension is considered as two things in the Nova V2.1 API:
v2.1 API had plugin framework which was using stevedore to load Nova REST
API extensions instead of old V2 handcrafted extension load mechanism.
There was an argument that the plugin framework supported extensibility in
the Nova API to allow deployers to publish custom API resources.
* The '/extensions' API
In Newton release, config options of blacklist and whitelist extensions and
stevedore things were deprecated and marked for removal.
This API exposed the list of enabled API functions to users
by GET method. However as the above, new API extensions
should not be added to the list of this API.
In Pike, stevedore based plugin framekwork has been removed and url mapping
is done with plain router list. No more dynamic magic of detecting API
implementation for url.
The '/extensions' API is frozen in Nova V2.1 API and is deprecated.
The '/extensions' API exposed the list of enabled API functions to users
by GET method. However as the above, new API extensions should not be added
to the list of this API. The '/extensions' API is frozen in Nova V2.1 API and
is deprecated.
* The plugin framework
Things which are History now
****************************
One of the improvements in the V2.1 API was using stevedore to load
Nova REST API extensions instead of old V2 handcrafted extension load
mechanism.
Till Pike release, many deprecated things have been removed and became
history in Nova API world:
There was an argument that the plugin framework supported extensibility in
the Nova API to allow deployers to publish custom API resources.
From Nove V2.1 REST API, the concept of core API and extension API is
eliminated also. There is no difference between Nova V2.1 REST API,
all of them are part of Nova stable REST API.
* v2 legacy framework.
* API extensions concept.
* Stevedore magic to load the extension/plugin dynamically.
* Configurable way to enable/disable APIs extensions.