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/
v1.0/…). 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+xml). A version
MIME type is always linked to a base MIME type
(application/xml or application/json). If conflicting
versions are specified using both an HTTP header and a
URI, the URI takes precedence.
Example 1.22. Request with MIME type versioning
GET /214412/images HTTP/1.1
Host: servers.api.openstack.org
Accept: application/vnd.openstack.compute.v2+xml
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
Example 1.23. Request with URI versioning
GET /v2/214412/images HTTP/1.1
Host: servers.api.openstack.org
Accept: application/xml
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
![[Note]](../common/images/admon/note.png) | Note |
|---|---|
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) will follow providing links and MIME types to available versions.
Example 1.24. Multiple choices: XML response
<?xml version="1.0" encoding="UTF-8"?>
<choices xmlns="http://docs.openstack.org/common/api/v1.0"
xmlns:atom="http://www.w3.org/2005/Atom">
<version id="v1.0" status="DEPRECATED">
<media-types>
<media-type base="application/xml"
type="application/vnd.openstack.compute.v1.0+xml"/>
<media-type base="application/json"
type="application/vnd.openstack.compute.v1.0+json"/>
</media-types>
<atom:link rel="self"
href="http://servers.api.openstack.org/v1.0/1234/servers/52415800-8b69-11e0-9b19-734f6af67565"
/>
</version>
<version id="v2" status="CURRENT">
<media-types>
<media-type base="application/xml"
type="application/vnd.openstack.compute.v2+xml"/>
<media-type base="application/json"
type="application/vnd.openstack.compute.v2+xml"/>
</media-types>
<atom:link rel="self"
href="http://servers.api.openstack.org/v2/1234/servers/52415800-8b69-11e0-9b19-734f6af67565"
/>
</version>
</choices>
Example 1.25. Multiple choices: JSON response
{
"choices": [
{
"id": "v1.0",
"status": "DEPRECATED",
"links": [
{
"rel": "self",
"href": "http://servers.api.openstack.org/v1.0/1234/servers/52415800-8b69-11e0-9b19-734f6af67565"
}
],
"media-types": [
{
"base": "application/xml",
"type": "application/vnd.openstack.compute.v1.0+xml"
},
{
"base": "application/json",
"type": "application/vnd.openstack.compute.v1.0+json"
}
]
},
{
"id": "v2",
"status": "CURRENT",
"links": [
{
"rel": "self",
"href": "http://servers.api.openstack.org/v2/1234/servers/52415800-8b69-11e0-9b19-734f6af67565"
}
],
"media-types": [
{
"base": "application/xml",
"type": "application/vnd.openstack.compute.v2+xml"
},
{
"base": "application/json",
"type": "application/vnd.openstack.compute.v2+json"
}
]
}
]
}
New features and functionality that do not break
API-compatibility will be introduced in the current
version of the API as extensions (see below) and the
URI and MIME types will remain unchanged. Features or
functionality changes that would necessitate a break
in API-compatibility will require a new version, which
will result in URI and MIME type version being updated
accordingly. When new API versions are released, older
versions will be marked as DEPRECATED.
Providers should work with developers and partners to
ensure there is adequate time to migrate to the new
version before deprecated versions are
discontinued.
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. Note that an Atom
representation of the versions resources is supported
when issuing a request with the Accept
header containing application/atom+xml or by adding a
.atom to the request URI. This allows standard Atom
clients to track version changes.
Normal Response Code(s): 200, 203
Error Response Code(s): 400, 413, 500, 503
This operation does not require a request body.
Example 1.27. List versions: XML response
<?xml version="1.0" encoding="UTF-8"?>
<versions xmlns="http://docs.openstack.org/common/api/v1.0"
xmlns:atom="http://www.w3.org/2005/Atom">
<version id="v1.0" status="DEPRECATED"
updated="2009-10-09T11:30:00Z">
<atom:link rel="self"
href="http://servers.api.openstack.org/v1.0/"/>
</version>
<version id="v2" status="CURRENT"
updated="2010-12-12T18:30:02.25Z">
<atom:link rel="self"
href="http://servers.api.openstack.org/v2/"/>
</version>
</versions>
Example 1.28. List versions: Atom response
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
<title type="text">Available API Versions</title>
<updated>2010-12-12T18:30:02.25Z</updated>
<id>http://servers.api.openstack.org/</id>
<author><name>Rackspace</name><uri>http://www.rackspace.com/</uri></author>
<link rel="self" href="http://servers.api.openstack.org/"/>
<entry>
<id>http://servers.api.openstack.org/v2/</id>
<title type="text">Version v2</title>
<updated>2010-12-12T18:30:02.25Z</updated>
<link rel="self" href="http://servers.api.openstack.org/v2/"/>
<content type="text">Version v2 CURRENT (2010-12-12T18:30:02.25Z)</content>
</entry>
<entry>
<id>http://servers.api.openstack.org/v1.0/</id>
<title type="text">Version v1.0</title>
<updated>2009-10-09T11:30:00Z</updated>
<link rel="self" href="http://servers.api.openstack.org/v1.0/"/>
<content type="text">Version v1.0 DEPRECATED (2009-10-09T11:30:00Z)</content>
</entry>
</feed>
Example 1.29. List versions: JSON response
{
"versions": [
{
"id": "v1.0",
"status": "DEPRECATED",
"updated": "2009-10-09T11:30:00Z",
"links": [
{
"rel": "self",
"href": "http://servers.api.openstack.org/v1.0/"
}
]
},
{
"id": "v2",
"status": "CURRENT",
"updated": "2010-12-12T18:30:02.25Z",
"links": [
{
"rel": "self",
"href": "http://servers.api.openstack.org/v2/"
}
]
}
]
}
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/). Version request URLs should always end with a trailing slash (/). If the slash is omitted, the server may respond with a 302 redirection request. Format extensions may be placed after the slash (e.g. https://servers.api.openstack.org/v2/.xml). Note that this is a special case that does not hold true for other API requests. In general, requests such as /servers.xml and /servers/.xml are handled equivalently.
Normal Response Code(s): 200, 203
Error Response Code(s): computeFault (400, 500, …), serviceUnavailable (503), unauthorized (401), forbidden (403), badRequest (400), badMethod (405), overLimit (413)
This operation does not require a request body
Example 1.31. Get version details: XML response
<?xml version="1.0" encoding="UTF-8"?>
<version xmlns="http://docs.openstack.org/common/api/v1.0"
xmlns:atom="http://www.w3.org/2005/Atom" id="v2" status="CURRENT"
updated="2011-01-21T11:33:21-06:00">
<media-types>
<media-type base="application/xml"
type="application/vnd.openstack.compute.v2+xml"/>
<media-type base="application/json"
type="application/vnd.openstack.compute.v2+json"/>
</media-types>
<atom:link rel="self" href="http://servers.api.openstack.org/v2/"/>
<atom:link rel="describedby" type="application/pdf"
href="http://docs.rackspacecloud.com/servers/api/v2/cs-devguide-20110125.pdf"/>
<atom:link rel="describedby" type="application/vnd.sun.wadl+xml"
href="http://docs.rackspacecloud.com/servers/api/v2/application.wadl"
/>
</version>
Example 1.32. Get version details: Atom response
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
<title type="text">About This Version</title>
<updated>2011-01-21T11:33:21-06:00</updated>
<id>http://servers.api.openstack.org/v1.0/</id>
<author><name>Rackspace</name><uri>http://www.rackspace.com/</uri></author>
<link rel="self" href="http://servers.api.openstack.org/v1.0/"/>
<entry>
<id>http://servers.api.openstack.org/v1.0/</id>
<title type="text">Version v2</title>
<updated>2011-01-21T11:33:21-06:00</updated>
<link rel="self" href="http://servers.api.openstack.org/v1.0/"/>
<link rel="describedby" type="application/pdf"
href="http://docs.rackspacecloud.com/servers/api/v2/cs-devguide-20110125.pdf"/>
<link rel="describedby" type="application/vnd.sun.wadl+xml"
href="http://docs.rackspacecloud.com/servers/api/v2/application.wadl"/>
<content type="text">Version v2 CURRENT (2011-01-21T11:33:21-06:00)</content>
</entry>
</feed>
Example 1.33. Get version details: JSON response
{
"version" : {
"id" : "v2",
"status" : "CURRENT",
"updated" : "2011-01-21T11:33:21-06:00",
"links": [
{
"rel" : "self",
"href" : "http://servers.api.openstack.org/v2/"
},
{
"rel" : "describedby",
"type" : "application/pdf",
"href" : "http://docs.rackspacecloud.com/servers/api/v2/cs-devguide-20110125.pdf"
},
{
"rel" : "describedby",
"type" : "application/vnd.sun.wadl+xml",
"href" : "http://docs.rackspacecloud.com/servers/api/v2/application.wadl"
}
],
"media-types": [
{
"base" : "application/xml",
"type" : "application/vnd.openstack.compute.v2+xml"
},
{
"base" : "application/json",
"type" : "application/vnd.openstack.compute.v2+json"
}
]
}
}
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).
| Note |
|---|---|
If a discrepancy exists between the two References, the WADL is authoritative as it contains the most accurate and up-to-date description of the API service. |
