d0e49e1b41
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
77 lines
2.8 KiB
ReStructuredText
77 lines
2.8 KiB
ReStructuredText
=========================
|
|
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.
|
|
|
|
.. _Nova versioning documentation: http://docs.openstack.org/developer/nova/api_microversion_dev.html#when-do-i-need-a-new-microversion
|
|
|
|
REST API Versions History
|
|
-------------------------
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
|
|
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.
|