28a399a13c
This commit does several things, which were just easier to do together. - Adds a new "misc" page describing the /v1/lookup and /v1/heartbeat resources. - Adds descriptions of the node.resource_class and node.network_interface fields that were introduced into the API but not into the documentation. - Introduces a new script, api-ref/regenerate-samples.sh, which can be used with Ironic to automate the generation of most of the sample files used in the api-ref documententation. - Corrects several errors in the sample JSON files that rendered errors when using them with curl for POST, PUT, or PATCH. - Uses the aforementioned regenerate-samples.sh script to regenerate most of the JSON result samples, ensuring that they are all up to date with the v1.22 API microversion. - Removes a few old/incorrect "Error Code" listings. - Updates the index page to remove extraneous wording. Change-Id: I764cbb43be15f05ba681de6ce1be1ae7c022173d
81 lines
2.0 KiB
ReStructuredText
81 lines
2.0 KiB
ReStructuredText
.. -*- rst -*-
|
|
|
|
============
|
|
API versions
|
|
============
|
|
|
|
Concepts
|
|
========
|
|
|
|
In order to bring new features to users over time, the Ironic API
|
|
supports versioning. There are two kinds of versions in Ironic.
|
|
|
|
- ''major versions'', which have dedicated urls.
|
|
- ''microversions'', which can be requested through the use of the
|
|
``X-OpenStack-Ironic-API-Version`` header.
|
|
|
|
The Version APIs work differently from other APIs as they *do not* require authentication.
|
|
|
|
Beginning with the Kilo release, all API requests support the
|
|
``X-OpenStack-Ironic-API-Version`` header. This header SHOULD be supplied
|
|
with every request; in the absence of this header, each request is treated
|
|
as though coming from an older pre-Kilo client. This was done to preserve
|
|
backwards compatibility as we introduced new features in the server.
|
|
|
|
List API versions
|
|
=================
|
|
|
|
.. rest_method:: GET /
|
|
|
|
This fetches all the information about all known major API versions in the
|
|
deployment. Links to more specific information will be provided for each major
|
|
API version, as well as information about supported min and max microversions.
|
|
|
|
Normal response codes: 200
|
|
|
|
Request
|
|
-------
|
|
|
|
Response Example
|
|
----------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- description: description
|
|
- versions: versions
|
|
- version: version
|
|
- id: id
|
|
- links: links
|
|
- min_version: x-openstack-ironic-api-min-version
|
|
|
|
.. literalinclude:: samples/api-root-response.json
|
|
:language: javascript
|
|
|
|
|
|
Show v1 API
|
|
===========
|
|
|
|
.. rest_method:: GET /v1/
|
|
|
|
Show all the resources within the Ironic v1 API.
|
|
|
|
Normal response codes: 200
|
|
|
|
Request
|
|
-------
|
|
|
|
Response Example
|
|
----------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- id: id
|
|
- links: links
|
|
- openstack-request-id: openstack-request-id
|
|
- x-openstack-ironic-api-version: header_version
|
|
- x-openstack-ironic-api-min-version: x-openstack-ironic-api-min-version
|
|
- x-openstack-ironic-api-max-version: x-openstack-ironic-api-max-version
|
|
|
|
.. literalinclude:: samples/api-v1-root-response.json
|
|
:language: javascript
|