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 Identity service (keystone). 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 |
| … | … |
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 |
| … | … |
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.