The OpenStack Identity 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
(for example, https://identity.api.openstack.org/ v2.0/…).
The MIME type versioning scheme uses HTTP content
negotiation where the Accept or
Content-Type headers contains a MIME type
that includes the version ID as a parameter
(application/vnd.openstack.identity+xml;version=1.1). 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.11. Request with MIME type versioning
GET /tenants HTTP/1.1
Host: identity.api.openstack.org
Accept: application/vnd.openstack.identity+xml;version=1.1
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
Example 1.12. Request with URI versioning
GET /v1.1/tenants HTTP/1.1
Host: identity.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 creation of permanent links, because the version scheme is not specified in the URI path: https://api.identity.openstack.org/tenants/12234. |
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.13. Multiple Choices Response: XML
<?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.identity+xml;version=1.0" />
<media-type
base="application/json"
type="application/vnd.openstack.identity+json;version=1.0" />
</media-types>
<atom:link rel="self" href="http://identity.api.openstack.org/v1.0" />
</version>
<version id="v1.1" status="CURRENT">
<media-types>
<media-type
base="application/xml"
type="application/vnd.openstack.identity+xml;version=1.1" />
<media-type
base="application/json"
type="application/vnd.openstack.identity+json;version=1.1" />
</media-types>
<atom:link rel="self" href="http://identity.api.openstack.org/v1.1" />
</version>
<version id="v2.0" status="BETA">
<media-types>
<media-type
base="application/xml"
type="application/vnd.openstack.identity+xml;version=2.0" />
<media-type
base="application/json"
type="application/vnd.openstack.identity+json;version=2.0" />
</media-types>
<atom:link rel="self" href="http://identity.api.openstack.org/v2.0" />
</version>
</choices>
Example 1.14. Multiple Choices Response: JSON
{
"choices":[{
"id": "v1.0",
"status": "DEPRECATED",
"links":[{
"rel": "self",
"href": "http://identity.api.openstack.org/v1.0"
}
],
"media-types":{
"values":[{
"base": "application/xml",
"type": "application/vnd.openstack.identity+xml;version=1.0"
},
{
"base": "application/json",
"type": "application/vnd.openstack.identity+json;version=1.0"
}
]
}
},
{
"id": "v1.1",
"status": "CURRENT",
"links":[{
"rel": "self",
"href": "http://identity.api.openstack.org/v1.1"
}
],
"media-types":{
"values":[{
"base": "application/xml",
"type": "application/vnd.openstack.identity+xml;version=1.1"
},
{
"base": "application/json",
"type": "application/vnd.openstack.identity+json;version=1.1"
}
]
}
},
{
"id": "v2.0",
"status": "BETA",
"links":[{
"rel": "self",
"href": "http://identity.api.openstack.org/v2.0"
}
],
"media-types":{
"values":[{
"base": "application/xml",
"type": "application/vnd.openstack.identity+xml;version=2.0"
},
{
"base": "application/json",
"type": "application/vnd.openstack.identity+json;version=2.0"
}
]
}
}
],
"choices_links": ""
}
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 (such as, 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): badRequest (400), identityFault (500), serviceUnavailable(503)
This operation does not require a request body.
Example 1.16. Versions List Response: XML
<?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://identity.api.openstack.org/v1.0/"/>
</version>
<version id="v1.1" status="CURRENT"
updated="2010-12-12T18:30:02.25Z">
<atom:link rel="self"
href="http://identity.api.openstack.org/v1.1/"/>
</version>
<version id="v2.0" status="BETA"
updated="2011-05-27T20:22:02.25Z">
<atom:link rel="self"
href="http://identity.api.openstack.org/v2.0/"/>
</version>
</versions>
Example 1.17. Versions List Response: Atom
<?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://identity.api.openstack.org/</id>
<author><name>OpenStack</name><uri>http://www.openstack.org/</uri></author>
<link rel="self" href="http://identity.api.openstack.org/"/>
<entry>
<id>http://identity.api.openstack.org/v2.0/</id>
<title type="text">Version v2.0</title>
<updated>2011-05-27T20:22:02.25Z</updated>
<link rel="self" href="http://identity.api.openstack.org/v2.0/"/>
<content type="text">Version v2.1 CURRENT (2011-05-27T20:22:02.25Z)</content>
</entry>
<entry>
<id>http://identity.api.openstack.org/v1.1/</id>
<title type="text">Version v1.1</title>
<updated>2010-12-12T18:30:02.25Z</updated>
<link rel="self" href="http://identity.api.openstack.org/v1.1/"/>
<content type="text">Version v1.1 CURRENT (2010-12-12T18:30:02.25Z)</content>
</entry>
<entry>
<id>http://identity.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://identity.api.openstack.org/v1.0/"/>
<content type="text">Version v1.0 DEPRECATED (2009-10-09T11:30:00Z)</content>
</entry>
</feed>
Example 1.18. Versions List Response: JSON
{
"versions":[{
"id": "v1.0",
"status": "DEPRECATED",
"updated": "2009-10-09T11:30:00Z",
"links":[{
"rel": "self",
"href": "http://identity.api.openstack.org/v1.0/"
}
]
},
{
"id": "v1.1",
"status": "CURRENT",
"updated": "2010-12-12T18:30:02.25Z",
"links":[{
"rel": "self",
"href": "http://identity.api.openstack.org/v1.1/"
}
]
},
{
"id": "v2.0",
"status": "BETA",
"updated": "2011-05-27T20:22:02.25Z",
"links":[{
"rel": "self",
"href": "http://identity.api.openstack.org/v2.0/"
}
]
}
],
"versions_links":[]
}
You can also obtain additional information about a specific version by performing a GET on the base version URL (for example, https://identity.api.openstack.org/v1.1/). 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 (for example, https://identity.api.openstack.org/v1.1/.xml). Note that this is a special case that does not hold true for other API requests. In general, requests such as /tenants.xml and /tenants/.xml are handled equivalently.
Normal Response Code(s):200, 203
Error Response Code(s): badRequest (400), identityFault (500), serviceUnavailable(503)
This operation does not require a request body.
Example 1.20. Version Details Response: XML
<?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.0" status="CURRENT" updated="2011-01-21T11:33:21-06:00">
<media-types>
<media-type base="application/xml"
type="application/vnd.openstack.identity+xml;version=2.0"/>
<media-type base="application/json"
type="application/vnd.openstack.identity+json;version=2.0"/>
</media-types>
<atom:link rel="self"
href="http://identity.api.openstack.org/v2.0/"/>
<atom:link rel="describedby"
type="application/pdf"
href="http://docs.openstack.org/identity/api/v2.0/identity-latest.pdf" />
<atom:link rel="describedby"
type="application/vnd.sun.wadl+xml"
href="http://docs.openstack.org/identity/api/v2.0/identity.wadl" />
</version>
Example 1.21. Version Details Response: Atom
<?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://identity.api.openstack.org/v2.0/</id>
<author><name>OpenStack</name><uri>http://www.openstack.org/</uri></author>
<link rel="self" href="http://identity.api.openstack.org/v2.0/"/>
<entry>
<id>http://identity.api.openstack.org/v2.0/</id>
<title type="text">Version v2.0</title>
<updated>2011-01-21T11:33:21-06:00</updated>
<link rel="self" href="http://identity.api.openstack.org/v2.0/"/>
<link rel="describedby" type="application/pdf"
href="http://docs.openstack.org/api/identity/api/v2.0/identity-latest.pdf"/>
<link rel="describedby" type="application/vnd.sun.wadl+xml"
href="http://docs.openstack.org/identity/api/v2.0/application.wadl"/>
<content type="text">Version v2.0 CURRENT (2011-01-21T11:33:21-06:00)</content>
</entry>
</feed>
Example 1.22. Version Details Response: JSON
{
"version": {
"id": "v2.0",
"status": "CURRENT",
"updated": "2011-01-21T11:33:21-06:00",
"links": [
{
"rel": "self",
"href": "http://identity.api.openstack.org/v2.0/"
}, {
"rel": "describedby",
"type": "application/pdf",
"href": "http://docs.openstack.org/api/identity/api/v2.0/identity-latest.pdf"
}, {
"rel": "describedby",
"type": "application/vnd.sun.wadl+xml",
"href": "http://docs.openstack.org/identity/api/v2.0/identity.wadl"
}
],
"media-types": [
{
"base": "application/xml",
"type": "application/vnd.openstack.identity+xml;version=2.0"
}, {
"base": "application/json",
"type": "application/vnd.openstack.identity+json;version=2.0"
}
]
}
}
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 there is a discrepancy between the two specifications, the WADL is authoritative as it contains the most accurate and up-to-date description of the API service. |
