The API versioning schemes in use in OpenStack vary between services and have evolved since the early days of OpenStack. There are two types of API versioning to consider: the major version and the minor version. Today, most OpenStack services have settled on a single major API version and have chosen to evolve the API without bumping the major API version any further. There are three API minor versioning schemes in common use.
Per-release versions
This is used by the Image service (glance) and DNS service (designate). All changes to the API during a given release cycle are gathered into a single new API version. As such, the API version will increase at most once per release. You can continue to request older versions.
For example, consider the Image (glance) API.
| Release | Supported 2.x API versions |
|---|---|
| Grizzly | 2.0 - 2.1 |
| Havana | 2.0 - 2.2 |
| Kilo | 2.0 - 2.3 |
| … | … |
In theory, this means the API is purely additive and the new version can be used as a signal that an API addition is available. Glance takes this a step further and includes or excludes API versions depending on whether an optional feature is enabled or not.
Single version
This is used by the Identity service (keystone). It is similar to the per-release versions but unlike those, only a single API version is exposed. Like those, however, this version can be used as signal that a feature is available. Once again, this API schema is really intended to be purely additive, since there’s no way to opt into old behavior. Keystone, for example, has never removed APIs or made non-additive changes like changing the type of a field or removing it.
Microversions
This is used by multiple services including the Compute service (nova), Block Storage service (cinder), and Shared Filesystem service (manila). Each change to the API will result in a new API version. As such, the API version can increase multiple times per release. You can continue to request older versions.
For example, consider the Compute (nova) API.
| Release | Supported 2.x API versions |
|---|---|
| Kilo | 2.1 - 2.3 |
| Liberty | 2.1 - 2.12 |
| Mitaka | 2.1 - 2.25 |
| … | … |
Unlike the previous examples, this API versioning schema allows for practically any change, including changing the type of a field, adding and removing new fields, and adding or removing new APIS. If you want the old behavior, you simply request an older microversion.
Extensions
This is used by the Networking service (neutron). It’s a versioning scheme that doesn’t use API versions. Instead, it exposes a list of available extensions. An extension can add, remove or modify features and vendor-specific functionality to the API. This can include API resources/routes as well as new fields in API requests and responses. If you want to depend on a feature added by an extension, you should check if the extension is present.