138a3eae7d
This fixes a number of issues in the versions.inc reference
document.
Documents all the useful parameters in the response (we really need to
do something about the ones that are not).
Fix links to samples content, and write some text explaining them.
Parametrize the {api_version} GET call, it was weird to list all the
hard coded values there.
Add a couple of inline todos for longer additional references we
should do.
Part of bp:api-ref-in-rst
Change-Id: I56e5e922fca39453d0d9fc062a84daba7cad8cc1
110 lines
2.6 KiB
ReStructuredText
110 lines
2.6 KiB
ReStructuredText
.. -*- rst -*-
|
|
|
|
==============
|
|
API Versions
|
|
==============
|
|
|
|
Concepts
|
|
========
|
|
|
|
In order to bring new features to users over time, the Nova API
|
|
supports versioning. There are two kinds of versions in Nova.
|
|
|
|
- ''major versions'', which have dedicated urls
|
|
- ''microversions'', which can be requested through the use of the
|
|
``X-OpenStack-Nova-API-Version`` header
|
|
|
|
.. TODO(sdague): build a more detailed link to using Microversions on
|
|
requests.
|
|
|
|
List All Major 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 API version, as well as information about supported min and
|
|
max microversions.
|
|
|
|
Normal Response Codes: 200, 300
|
|
|
|
Response
|
|
--------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- x-openstack-request-id: x-openstack-request-id
|
|
- versions: versions
|
|
- id: version_id
|
|
- status: version_status
|
|
- links: links
|
|
- version: version_max
|
|
- min_version: version_min
|
|
|
|
.. note::
|
|
|
|
The ``updated`` parameter in the response is vestigial and provides
|
|
no useful information.
|
|
|
|
Response Example
|
|
----------------
|
|
|
|
This demonstrates the expected response from a bleeding edge server
|
|
that supports up to the current microversion. When querying OpenStack
|
|
environments you will typically find the current microversion on the
|
|
v2.1 API is lower than listed below.
|
|
|
|
.. literalinclude:: /../../doc/api_samples/versions/versions-get-resp.json
|
|
:language: javascript
|
|
|
|
|
|
Show Details of Specific API Version
|
|
====================================
|
|
|
|
.. rest_method:: GET /{api_version}
|
|
|
|
This gets the details of a specific API at it's root. Nearly all this
|
|
information exists at the API root, so this is mostly a redundant
|
|
operation.
|
|
|
|
.. TODO(sdague) we should probably deprecate this call as everything
|
|
that's needed is really in the root now
|
|
|
|
Normal Response Codes: 200
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- api_version: api_version
|
|
|
|
Response
|
|
--------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- x-openstack-request-id: x-openstack-request-id
|
|
- version: version
|
|
- id: version_id
|
|
- status: version_status
|
|
- links: links
|
|
- version: version_max
|
|
- min_version: version_min
|
|
|
|
.. note::
|
|
|
|
The ``updated`` and ``media-types`` parameters in the response are
|
|
vestigial and provide no useful information. They will probably be
|
|
deprecated and removed in the future.
|
|
|
|
|
|
Response Example
|
|
----------------
|
|
|
|
This is an example of a ``GET /v2.1`` on a relatively current server.
|
|
|
|
.. literalinclude:: /../../doc/api_samples/versions/v21-version-get-resp.json
|
|
:language: javascript
|