1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
|
..
Copyright 2015 Intel
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Nova Stable REST API
====================
This document describes both the current state of the Nova REST API -- as
of the Pike release -- and also attempts to describe how the Nova team
evolved the REST API's implementation over time and removed 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
/nova/api/openstack/compute/legacy_v2/ directory. This code tree was totally
removed during Newton release time frame (14.0.0 and later).
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.1 API is the new Nova REST API with a set of improvements which
includes `Microversion <https://docs.openstack.org/api-guide/compute/microversions.html>`_
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).
Current Stable API
------------------
* 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 used 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
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.
In the Newton release, stevedore loading of API extension plugins was
deprecated and marked for removal.
In the 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 the 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 be added via microversion concept and use the
microversioning decorators to add or change the REST 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.
In the Newton release, config options of blacklist and whitelist extensions and
stevedore things were deprecated and marked for removal.
In Pike, stevedore based plugin framework has been removed and url mapping
is done with plain router list. There is no more dynamic magic of detecting API
implementation for url. See :doc:`Extending the API </contributor/api>`
for more information.
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 <https://docs.openstack.org/api-ref/compute/#extensions-extensions-deprecated>`_.
Things which are History now
****************************
As of the Pike release, many deprecated things have been removed and became
history in Nova API world:
* v2 legacy framework
* API extensions concept
* stevedore magic to load the extension/plugin dynamically
* Configurable way to enable/disable APIs extensions
|
