openstack/ironic
Code Issues Proposed changes
e26c71bcf6
ironic/doc/source/dev/webapi.rst
Devananda van der Veen d0e49e1b41 Documentation update 
This patch contains several changes to the documentation which
were brought about by, initially, removing the webapi/v1 page and
replacing it with a link to the /api-ref/ page.

As I did that, I saw that our front page (index.html) needed to
be updated as well, and decided that the front page needed to
actually be completely rerwitten -- while preserving all the links.

Some of the TOC links from the front page were malformed because
subpages included more than one H1 heading, so I had to make small
changes in the api-audit-support and code-contribution-guide and
dev-quickstart pages, in order for the front page to render properly.

As I corrected the headings on dev-quickstart, I realized the page
was not comprehensively organized, and so decided to reorganize the
sections and make it easier to navigate.

Here is a bullet-point summary of this change:
* Major changes to content and organization of index page
* Moved the version history from webapi/v1 to dev/webapi-version-history
* Added API conceptual guide at dev/webapi
* Replaced webapi/v1 with a link to dev/webapi, in case anyone
  bookmarked it
* Removed doc references to webapi/v1
* Merged the pages dev/contributing and dev/code-contribution-guide
* Removed duplicate H1 headers in deploy/api-audit-support
* Reorganized and renamed section headers in dev/dev-quickstart,
  and made some substantive corrections and changes as well
* Updated wording at the top of the index and deploy/user-guide pages.

Change-Id: Ib418e1d4fdfab4f0e15560270f39922e33df3f12
2016-08-23 12:49:04 -07: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 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 <dev/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.