REST API Conceptual Guide¶
The ironic REST API supports two types of versioning:
“major versions”, which have dedicated urls.
“microversions”, which can be requested through the use of the
There is only one major version supported currently, “v1”. As such, most URLs in this documentation are written with the “/v1/” prefix.
Starting with the Kilo release, ironic supports microversions. In this context,
a version is defined as a string of 2 integers separated by a dot: X.Y.
X is a major version, always equal to
a minor version. Server minor version is increased every time the API behavior
is changed (note Exceptions from Versioning).
Nova versioning documentation has a nice guide for developers on when to bump an API version.
The server indicates its minimum and maximum supported API versions in the
X-OpenStack-Ironic-API-Maximum-Version headers respectively, returned
with every response. Client may request a specific API version by providing
X-OpenStack-Ironic-API-Version header with request.
The requested microversion determines both the allowable requests and the response format for all requests. A resource may be represented differently based on the requested microversion.
If no version is requested by the client, the minimum supported version will be assumed. In this way, a client is only exposed to those API features that are supported in the requested (explicitly or implicitly) API version (again note Exceptions from Versioning, they are not covered by this rule).
We recommend clients that require a stable API to always request a specific version of API that they have been tested against.
A special value
latest can be requested instead a numerical
microversion, which always requests the newest supported API version from
REST API Versions History¶
Exceptions from Versioning¶
The following API-visible things are not covered by the API versioning:
Current node state is always exposed as it is, even if not supported by the requested API version, with exception of
availablestate, which is returned in version 1.1 as
None(in Python) or
Data within free-form JSON attributes:
driver_internal_infofields on a node object;
extrafields on all objects.
Addition of new drivers.
All vendor passthru methods.