openstack/ironic
Code Issues Proposed changes
261e66bbad
ironic/doc/source/contributor/webapi.rst
Riccardo Pittau a25589b20f docs: use openstackdocstheme extlink extension 
The extlink extension [1] ensures the urls have version-specific
references to other projects.

[1] https://docs.openstack.org/openstackdocstheme/latest/#external-link-helper

Change-Id: I0d5d445fae8a7ec60f6a9caacede7cc77770b36e
Story: 2006621
Task: 36825
2019-10-08 11:12:05 +02:00

2.8 KiB
Raw Blame History

REST API Conceptual Guide

Versioning

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 X-OpenStack-Ironic-API-Version header.

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. Here X is a major version, always equal to 1, and Y is a minor version. Server minor version is increased every time the API behavior is changed (note Exceptions from Versioning).

Note

Nova versioning documentation <contributor/microversions.html#when-do-i-need-a-new-microversion> 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-Minimum-Version and 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.

Note

A special value latest can be requested instead a numerical microversion, which always requests the newest supported API version from the server.

REST API Versions History

API Version History <webapi-version-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 available state, which is returned in version 1.1 as None (in Python) or null (in JSON).
  • Data within free-form JSON attributes: properties, driver_info, instance_info, driver_internal_info fields on a node object; extra fields on all objects.
  • Addition of new drivers.
  • All vendor passthru methods.