110b499b6a
Due to the migration of the OpenStack document library, some outdated links were found during use, using https instead of http and pointing to the right place. Change-Id: I1e37e15643b4ff7a7b22b2c7c39eba76d0cbdb39
112 lines
3.9 KiB
ReStructuredText
112 lines
3.9 KiB
ReStructuredText
========
|
||
Versions
|
||
========
|
||
|
||
The OpenStack Compute API uses both a URI and a MIME type versioning
|
||
scheme. In the URI scheme, the first element of the path contains the
|
||
target version identifier (e.g. https://servers.api.openstack.org/
|
||
v2.1/...). The MIME type versioning scheme uses HTTP content negotiation
|
||
where the ``Accept`` or ``Content-Type`` headers contains a MIME type
|
||
that identifies the version (application/vnd.openstack.compute.v2.1+json).
|
||
A version MIME type is always linked to a base MIME type, such as
|
||
application/json. If conflicting versions are specified using both an HTTP
|
||
header and a URI, the URI takes precedence.
|
||
|
||
**Example: Request with MIME type versioning**
|
||
|
||
.. code::
|
||
|
||
GET /214412/images HTTP/1.1
|
||
Host: servers.api.openstack.org
|
||
Accept: application/vnd.openstack.compute.v2.1+json
|
||
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
|
||
|
||
|
||
**Example: Request with URI versioning**
|
||
|
||
.. code::
|
||
|
||
GET /v2.1/214412/images HTTP/1.1
|
||
Host: servers.api.openstack.org
|
||
Accept: application/json
|
||
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
|
||
|
||
|
||
Permanent Links
|
||
~~~~~~~~~~~~~~~
|
||
|
||
The MIME type versioning approach allows for creating of permanent
|
||
links, because the version scheme is not specified in the URI path:
|
||
https://api.servers.openstack.org/224532/servers/123.
|
||
|
||
If a request is made without a version specified in the URI or via HTTP
|
||
headers, then a multiple-choices response (300) follows that provides
|
||
links and MIME types to available versions.
|
||
|
||
|
||
**Example: Multiple choices: JSON response**
|
||
|
||
.. code::
|
||
|
||
{
|
||
"choices": [
|
||
{
|
||
"id": "v2.0",
|
||
"links": [
|
||
{
|
||
"href": "http://servers.api.openstack.org/v2/7f5b2214547e4e71970e329ccf0b257c/servers/detail",
|
||
"rel": "self"
|
||
}
|
||
],
|
||
"media-types": [
|
||
{
|
||
"base": "application/json",
|
||
"type": "application/vnd.openstack.compute+json;version=2"
|
||
}
|
||
],
|
||
"status": "SUPPORTED"
|
||
},
|
||
{
|
||
"id": "v2.1",
|
||
"links": [
|
||
{
|
||
"href": "http://servers.api.openstack.org/v2.1/7f5b2214547e4e71970e329ccf0b257c/servers/detail",
|
||
"rel": "self"
|
||
}
|
||
],
|
||
"media-types": [
|
||
{
|
||
"base": "application/json",
|
||
"type": "application/vnd.openstack.compute+json;version=2.1"
|
||
}
|
||
],
|
||
"status": "CURRENT"
|
||
}
|
||
]
|
||
}
|
||
|
||
The API with ``CURRENT`` status is the newest API and continues to be improved by the
|
||
Nova project. The API with ``SUPPORTED`` status is the old API, where new features are
|
||
frozen. The API with ``DEPRECATED`` status is the API that will be removed in the
|
||
foreseeable future. Providers should work with developers and partners to
|
||
ensure there is adequate time to migrate to the new version before deprecated
|
||
versions are discontinued. For any API which is under development but isn't
|
||
released as yet, the API status is ``EXPERIMENTAL``.
|
||
|
||
Your application can programmatically determine available API versions
|
||
by performing a **GET** on the root URL (i.e. with the version and
|
||
everything following that truncated) returned from the authentication system.
|
||
|
||
You can also obtain additional information about a specific version by
|
||
performing a **GET** on the base version URL (such as,
|
||
``https://servers.api.openstack.org/v2.1/``). Version request URLs must
|
||
always end with a trailing slash (``/``). If you omit the slash, the
|
||
server might respond with a 302 redirection request.
|
||
|
||
For examples of the list versions and get version details requests and
|
||
responses, see `*API versions*
|
||
<https://developer.openstack.org/api-ref/compute/#api-versions>`__.
|
||
|
||
The detailed version response contains pointers to both a human-readable
|
||
and a machine-processable description of the API service.
|