openstack/nova
Code Issues Proposed changes
98713d69ac
nova/api-ref/source/versions.inc

109 lines
2.7 KiB
PHP
Raw Normal View History

Import RST files for documentation This is the results of the RST conversion from WADL. It creates a single index plus a bunch of included files which represent sections of the API document. This is the starting point for fixing the documentation. Change-Id: I7d561c2ecdcd864172dedb54a551f17ad3bdfe26
2016-04-12 09:03:46 -04:00
.. -*- rst -*-
clean up versions.inc reference document 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
2016-04-14 14:44:13 -04:00
==============
API Versions
==============
Import RST files for documentation This is the results of the RST conversion from WADL. It creates a single index plus a bunch of included files which represent sections of the API document. This is the starting point for fixing the documentation. Change-Id: I7d561c2ecdcd864172dedb54a551f17ad3bdfe26
2016-04-12 09:03:46 -04:00
clean up versions.inc reference document 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
2016-04-14 14:44:13 -04:00
In order to bring new features to users over time, the Nova API
supports versioning. There are two kinds of versions in Nova.
Import RST files for documentation This is the results of the RST conversion from WADL. It creates a single index plus a bunch of included files which represent sections of the API document. This is the starting point for fixing the documentation. Change-Id: I7d561c2ecdcd864172dedb54a551f17ad3bdfe26
2016-04-12 09:03:46 -04:00
clean up versions.inc reference document 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
2016-04-14 14:44:13 -04:00
- ''major versions'', which have dedicated urls
- ''microversions'', which can be requested through the use of the
[api-ref] Minor text clean-up, formatting - Cleaned up some wording, and formatted two rst notes. - Moved cloudpipe.inc in index.rst to be located with other deprecated apis. Change-Id: Ic3740540e8cc626110c77214acf87338e1abdd76
2016-11-29 12:31:46 -05:00
``X-OpenStack-Nova-API-Version`` header, or since microversion 2.27
Support for both microversion headers In this change the new OpenStack-API-Version headers is allowed, but not required, for requesting a microversion. Both headers are accepted in the request and both headers are sent in the response (both the header and its value, and the addition to the Vary header). Many tests which explicitly use a microversion header have been updated to use both. This change is not 100% as most of the tests are testing the handling of the value of the header, not which header is involved. Partially-Implements: blueprint modern-microversions Change-Id: I68da13b5ba0c2f3357523e765a5b9db81899daf1
2016-03-31 17:16:51 +01:00
the ``OpenStack-API-Version`` header may also be used.
Import RST files for documentation This is the results of the RST conversion from WADL. It creates a single index plus a bunch of included files which represent sections of the API document. This is the starting point for fixing the documentation. Change-Id: I7d561c2ecdcd864172dedb54a551f17ad3bdfe26
2016-04-12 09:03:46 -04:00
[api-ref] Minor text clean-up, formatting - Cleaned up some wording, and formatted two rst notes. - Moved cloudpipe.inc in index.rst to be located with other deprecated apis. Change-Id: Ic3740540e8cc626110c77214acf87338e1abdd76
2016-11-29 12:31:46 -05:00
For more details about Microversions, please reference:
Fix the versions API for api-ref * Add doc for request without version in the url * Add a link reference for microversion detail Part of bp:api-ref-in-rst Change-Id: Iadee4623fe70c43ad38c087e027f7e4cf01fea12
2016-04-21 10:52:04 +08:00
`Microversions
Update api-ref location The api documentation is now published on docs.openstack.org instead of developer.openstack.org. Update all links that are changed to the new location. Note that Neutron publishes to api-ref/network, not networking anymore. Note that redirects will be set up as well but let's point now to the new location. For details, see: http://lists.openstack.org/pipermail/openstack-discuss/2019-July/007828.html Change-Id: Id2cf3aa252df6db46575b5988e4937ecfc6792bb
2019-07-22 18:08:40 +02:00
<https://docs.openstack.org/api-guide/compute/microversions.html>`_
Import RST files for documentation This is the results of the RST conversion from WADL. It creates a single index plus a bunch of included files which represent sections of the API document. This is the starting point for fixing the documentation. Change-Id: I7d561c2ecdcd864172dedb54a551f17ad3bdfe26
2016-04-12 09:03:46 -04:00
Add microversion cap information Currently we only publish the master branch of api-ref to: http://developer.openstack.org/api-ref/compute and we have microversion caps for different releases. It will be better for user to understand if we add also microversion caps information to the doc. Change-Id: Ic6c042f68f5d340a68abad6701e65d44e46da3a7 Closes-bug: #1640995
2016-11-11 15:05:09 +08:00
.. note:: The maximum microversion supported by each release varies.
Please reference:
`API Microversion History
Fix broken URLs Fix broken nova URLs that linked to the old developer/nova places and use the new link instead. Change-Id: Ideb50626e140201dded19fc82584440f1a407e47
2017-09-06 22:01:01 +02:00
<https://docs.openstack.org/nova/latest/reference/api-microversion-history.html>`__
Add microversion cap information Currently we only publish the master branch of api-ref to: http://developer.openstack.org/api-ref/compute and we have microversion caps for different releases. It will be better for user to understand if we add also microversion caps information to the doc. Change-Id: Ic6c042f68f5d340a68abad6701e65d44e46da3a7 Closes-bug: #1640995
2016-11-11 15:05:09 +08:00
for API microversion history details.
remove /v2.1/{tenant_id} from all urls As discussed at summit, the version part of the URL is not really relevant, or a thing a user should be filling out themselves, this should instead be set by the service catalog and extracted from the token. This removes it's reference in all documented REST urls, and adds a new section describing how one gets the base URL for all calls. Change-Id: I4306b8c3de0225e54f3909dd8a1fb293c4e5944c
2016-06-02 08:50:03 -04:00
The Version APIs work differently from other APIs as they *do not*
require authentication.
clean up versions.inc reference document 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
2016-04-14 14:44:13 -04:00
List All Major Versions
=======================
Import RST files for documentation This is the results of the RST conversion from WADL. It creates a single index plus a bunch of included files which represent sections of the API document. This is the starting point for fixing the documentation. Change-Id: I7d561c2ecdcd864172dedb54a551f17ad3bdfe26
2016-04-12 09:03:46 -04:00
clean up versions.inc reference document 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
2016-04-14 14:44:13 -04:00
.. rest_method:: GET /
Import RST files for documentation This is the results of the RST conversion from WADL. It creates a single index plus a bunch of included files which represent sections of the API document. This is the starting point for fixing the documentation. Change-Id: I7d561c2ecdcd864172dedb54a551f17ad3bdfe26
2016-04-12 09:03:46 -04:00
clean up versions.inc reference document 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
2016-04-14 14:44:13 -04:00
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.
Fix the versions API for api-ref * Add doc for request without version in the url * Add a link reference for microversion detail Part of bp:api-ref-in-rst Change-Id: Iadee4623fe70c43ad38c087e027f7e4cf01fea12
2016-04-21 10:52:04 +08:00
Normal Response Codes: 200
Import RST files for documentation This is the results of the RST conversion from WADL. It creates a single index plus a bunch of included files which represent sections of the API document. This is the starting point for fixing the documentation. Change-Id: I7d561c2ecdcd864172dedb54a551f17ad3bdfe26
2016-04-12 09:03:46 -04:00
Response
move sphinx h3 to '-' instead of '^' In the sphinx document h3 is supposed to be '-' not '^': =, for sections -, for subsections ^, for subsubsections We have to enforce consistency here because we're processing included files which all have to agree, otherwise it's a sphinx error. Part of bp:api-ref-in-rst Change-Id: Ic6eef5cacb07870f161b04b031e332f2b87aeedc
2016-04-14 13:10:59 -04:00
--------
Import RST files for documentation This is the results of the RST conversion from WADL. It creates a single index plus a bunch of included files which represent sections of the API document. This is the starting point for fixing the documentation. Change-Id: I7d561c2ecdcd864172dedb54a551f17ad3bdfe26
2016-04-12 09:03:46 -04:00
clean up versions.inc reference document 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
2016-04-14 14:44:13 -04:00
.. rest_parameters:: parameters.yaml
- versions: versions
- id: version_id
- links: links
- min_version: version_min
api-ref: Fix missing parameters in API Versions Add 'updated' and 'media-types' explicitly in parameter tables. Change-Id: I3e9f3374d4183d7ef7d3cb55cc95a4499ab20d49 Closes-Bug: #1634668
2017-06-19 13:13:09 +09:00
- status: version_status
- updated: updated_version
- version: version_max
Import RST files for documentation This is the results of the RST conversion from WADL. It creates a single index plus a bunch of included files which represent sections of the API document. This is the starting point for fixing the documentation. Change-Id: I7d561c2ecdcd864172dedb54a551f17ad3bdfe26
2016-04-12 09:03:46 -04:00
clean up versions.inc reference document 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
2016-04-14 14:44:13 -04:00
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
Import RST files for documentation This is the results of the RST conversion from WADL. It creates a single index plus a bunch of included files which represent sections of the API document. This is the starting point for fixing the documentation. Change-Id: I7d561c2ecdcd864172dedb54a551f17ad3bdfe26
2016-04-12 09:03:46 -04:00
:language: javascript
clean up versions.inc reference document 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
2016-04-14 14:44:13 -04:00
Show Details of Specific API Version
====================================
Fix version details API does not return 200 OK When use version details api http://ip/compute/v2 to get api details, it does not return 200 OK, and the return value is empty. This change is to correct the version details API URL. Change-Id: I6befb4df6b688ae8c59671781c4e7b338a16462c Closes-Bug: #1802247
2018-11-08 16:00:12 +08:00
.. rest_method:: GET /{api_version}/
Import RST files for documentation This is the results of the RST conversion from WADL. It creates a single index plus a bunch of included files which represent sections of the API document. This is the starting point for fixing the documentation. Change-Id: I7d561c2ecdcd864172dedb54a551f17ad3bdfe26
2016-04-12 09:03:46 -04:00
Trival fix typos in api-ref Trival fix typos in api-ref Change-Id: I98347db828a919dd9fa8f3c3ad51c7a048909176
2016-12-21 21:50:55 +08:00
This gets the details of a specific API at its root. Nearly all this
clean up versions.inc reference document 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
2016-04-14 14:44:13 -04:00
information exists at the API root, so this is mostly a redundant
operation.
Import RST files for documentation This is the results of the RST conversion from WADL. It creates a single index plus a bunch of included files which represent sections of the API document. This is the starting point for fixing the documentation. Change-Id: I7d561c2ecdcd864172dedb54a551f17ad3bdfe26
2016-04-12 09:03:46 -04:00
clean up versions.inc reference document 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
2016-04-14 14:44:13 -04:00
.. TODO(sdague) we should probably deprecate this call as everything
that's needed is really in the root now
Import RST files for documentation This is the results of the RST conversion from WADL. It creates a single index plus a bunch of included files which represent sections of the API document. This is the starting point for fixing the documentation. Change-Id: I7d561c2ecdcd864172dedb54a551f17ad3bdfe26
2016-04-12 09:03:46 -04:00
clean up versions.inc reference document 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
2016-04-14 14:44:13 -04:00
Normal Response Codes: 200
Import RST files for documentation This is the results of the RST conversion from WADL. It creates a single index plus a bunch of included files which represent sections of the API document. This is the starting point for fixing the documentation. Change-Id: I7d561c2ecdcd864172dedb54a551f17ad3bdfe26
2016-04-12 09:03:46 -04:00
Request
move sphinx h3 to '-' instead of '^' In the sphinx document h3 is supposed to be '-' not '^': =, for sections -, for subsections ^, for subsubsections We have to enforce consistency here because we're processing included files which all have to agree, otherwise it's a sphinx error. Part of bp:api-ref-in-rst Change-Id: Ic6eef5cacb07870f161b04b031e332f2b87aeedc
2016-04-14 13:10:59 -04:00
-------
Import RST files for documentation This is the results of the RST conversion from WADL. It creates a single index plus a bunch of included files which represent sections of the API document. This is the starting point for fixing the documentation. Change-Id: I7d561c2ecdcd864172dedb54a551f17ad3bdfe26
2016-04-12 09:03:46 -04:00
clean up versions.inc reference document 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
2016-04-14 14:44:13 -04:00
.. rest_parameters:: parameters.yaml
- api_version: api_version
Import RST files for documentation This is the results of the RST conversion from WADL. It creates a single index plus a bunch of included files which represent sections of the API document. This is the starting point for fixing the documentation. Change-Id: I7d561c2ecdcd864172dedb54a551f17ad3bdfe26
2016-04-12 09:03:46 -04:00
Response
move sphinx h3 to '-' instead of '^' In the sphinx document h3 is supposed to be '-' not '^': =, for sections -, for subsections ^, for subsubsections We have to enforce consistency here because we're processing included files which all have to agree, otherwise it's a sphinx error. Part of bp:api-ref-in-rst Change-Id: Ic6eef5cacb07870f161b04b031e332f2b87aeedc
2016-04-14 13:10:59 -04:00
--------
Import RST files for documentation This is the results of the RST conversion from WADL. It creates a single index plus a bunch of included files which represent sections of the API document. This is the starting point for fixing the documentation. Change-Id: I7d561c2ecdcd864172dedb54a551f17ad3bdfe26
2016-04-12 09:03:46 -04:00
clean up versions.inc reference document 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
2016-04-14 14:44:13 -04:00
.. rest_parameters:: parameters.yaml
Import RST files for documentation This is the results of the RST conversion from WADL. It creates a single index plus a bunch of included files which represent sections of the API document. This is the starting point for fixing the documentation. Change-Id: I7d561c2ecdcd864172dedb54a551f17ad3bdfe26
2016-04-12 09:03:46 -04:00
clean up versions.inc reference document 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
2016-04-14 14:44:13 -04:00
- version: version
- id: version_id
- links: links
api-ref: Fix missing parameters in API Versions Add 'updated' and 'media-types' explicitly in parameter tables. Change-Id: I3e9f3374d4183d7ef7d3cb55cc95a4499ab20d49 Closes-Bug: #1634668
2017-06-19 13:13:09 +09:00
- media-types: media_types
clean up versions.inc reference document 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
2016-04-14 14:44:13 -04:00
- min_version: version_min
api-ref: Fix missing parameters in API Versions Add 'updated' and 'media-types' explicitly in parameter tables. Change-Id: I3e9f3374d4183d7ef7d3cb55cc95a4499ab20d49 Closes-Bug: #1634668
2017-06-19 13:13:09 +09:00
- status: version_status
- updated: updated_version
- version: version_max
Import RST files for documentation This is the results of the RST conversion from WADL. It creates a single index plus a bunch of included files which represent sections of the API document. This is the starting point for fixing the documentation. Change-Id: I7d561c2ecdcd864172dedb54a551f17ad3bdfe26
2016-04-12 09:03:46 -04:00
clean up versions.inc reference document 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
2016-04-14 14:44:13 -04:00
Response Example
----------------
Import RST files for documentation This is the results of the RST conversion from WADL. It creates a single index plus a bunch of included files which represent sections of the API document. This is the starting point for fixing the documentation. Change-Id: I7d561c2ecdcd864172dedb54a551f17ad3bdfe26
2016-04-12 09:03:46 -04:00
Fix version details API does not return 200 OK When use version details api http://ip/compute/v2 to get api details, it does not return 200 OK, and the return value is empty. This change is to correct the version details API URL. Change-Id: I6befb4df6b688ae8c59671781c4e7b338a16462c Closes-Bug: #1802247
2018-11-08 16:00:12 +08:00
This is an example of a ``GET /v2.1/`` on a relatively current server.
Import RST files for documentation This is the results of the RST conversion from WADL. It creates a single index plus a bunch of included files which represent sections of the API document. This is the starting point for fixing the documentation. Change-Id: I7d561c2ecdcd864172dedb54a551f17ad3bdfe26
2016-04-12 09:03:46 -04:00
clean up versions.inc reference document 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
2016-04-14 14:44:13 -04:00
.. literalinclude:: /../../doc/api_samples/versions/v21-version-get-resp.json
Import RST files for documentation This is the results of the RST conversion from WADL. It creates a single index plus a bunch of included files which represent sections of the API document. This is the starting point for fixing the documentation. Change-Id: I7d561c2ecdcd864172dedb54a551f17ad3bdfe26
2016-04-12 09:03:46 -04:00
:language: javascript
Copy Permalink