7b0b8c3754
The concept doc should only talk about v2.1 API. This pach corrects them. Also use the current API response instead of the old one and correct some old reference link. blueprint complete-todo-in-api-concept-doc Change-Id: I90b39959a6a13f37ec0c03cf6f86943eba6c47d1
122 lines
4.3 KiB
ReStructuredText
122 lines
4.3 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 the 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 continue improved by the
|
||
Nova project. The API with ``SUPPORTED`` is the old API and new features is
|
||
frozen. The API with ``DEPRECATED`` status is the API 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 and didn't
|
||
release 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 to the right of it 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. Format extensions
|
||
can be placed after the slash (such as,
|
||
``https://servers.api.openstack.org/v2.1/.json``).
|
||
|
||
.. note:: This special case does not hold true for other API requests. In
|
||
general, requests such as ``/servers.json`` and ``/servers/.json`` are
|
||
handled equivalently.
|
||
|
||
For examples of the list versions and get version details requests and
|
||
responses, see `*API versions*
|
||
<http://developer.openstack.org/api-ref-compute-v2.1.html#versions-v2.1>`__.
|
||
|
||
The detailed version response contains pointers to both a human-readable
|
||
and a machine-processable description of the API service. The
|
||
machine-processable description is written in the Web Application
|
||
Description Language (WADL).
|
||
|