The OpenStack Compute API is extensible. Extensions
serve two purposes: They allow the introduction of new
features in the API without requiring a version change
and they allow the introduction of vendor specific
niche functionality. Applications can programmatically
list available extensions by performing a GET on the
/extensions
URI. Note that this is a
versioned request — that is, an extension
available in one API version might not be available in
another.
Extensions may also be queried individually by their unique alias. This provides the simplest method of checking if an extension is available as an unavailable extension will issue an itemNotFound (404) response.
Extensions may define new data types, parameters,
actions, headers, states, and resources. In XML,
additional elements and attributes may be defined.
These elements must be defined in the extension's
namespace. In JSON, the alias must be used. The
volumes element in the Examples 1.34 and 1.35 is defined in the RS-CBS
namespace.
Actions work in exactly the same manner as illustrated
in Examples 1.36 and 1.37.
Extended headers are always prefixed with
X-
followed by the alias and a dash:
(X-RS-CBS-HEADER1
). States and
parameters must be prefixed with the extension alias
followed by a colon. For example, an image may be in
the RS-PIE:PrepareShare
state.
Important | |
---|---|
Applications should be prepared to ignore
response data that contains extension elements. An
extended state should always be treated as an
|
Example 1.34. Extended server: XML response
<?xml version="1.0" encoding="UTF-8"?> <servers xmlns="http://docs.openstack.org/compute/api/v1.1" xmlns:atom="http://www.w3.org/2005/Atom"> <server id="52415800-8b69-11e0-9b19-734f6af67565" tenant_id="1234" user_id="5678" name="sample-server" status="BUILD" progress="60" hostId="e4d909c290d0fb1ca068ffaddf22cbd0" updated="2010-10-10T12:00:00Z" created="2010-08-10T12:00:00Z" accessIPv4="67.23.10.132" accessIPv6="::babe:67.23.10.132"> <image id="52415800-8b69-11e0-9b19-734f6f006e54"> <atom:link rel="self" href="http://servers.api.openstack.org/v2/1234/images/52415800-8b69-11e0-9b19-734f6f006e54"/> <atom:link rel="bookmark" href="http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f6f006e54" /> </image> <flavor id="52415800-8b69-11e0-9b19-734f216543fd"> <atom:link rel="self" href="http://servers.api.openstack.org/v2/1234/flavors/52415800-8b69-11e0-9b19-734f216543fd"/> <atom:link rel="bookmark" href="http://servers.api.openstack.org/1234/flavors/52415800-8b69-11e0-9b19-734f216543fd" /> </flavor> <metadata> <meta key="Server Label">Web Head 1</meta> <meta key="Image Version">2.1</meta> </metadata> <addresses> <network id="public"> <ip version="4" addr="67.23.10.132"/> <ip version="6" addr="::babe:67.23.10.132"/> <ip version="4" addr="67.23.10.131"/> <ip version="6" addr="::babe:4317:0A83"/> </network> <network id="private"> <ip version="4" addr="10.176.42.16"/> <ip version="6" addr="::babe:10.176.42.16"/> </network> </addresses> <atom:link rel="self" href="http://servers.api.openstack.org/v2/1234/servers/52415800-8b69-11e0-9b19-734f6af67565"/> <atom:link rel="bookmark" href="http://servers.api.openstack.org/1234/servers/52415800-8b69-11e0-9b19-734f6af67565"/> <volumes xmlns="http://docs.rackspacecloud.com/servers/api/ext/cbs/v1.0"> <volume name="OS" href="https://cbs.api.rackspacecloud.com/12934/volumes/19"/> <volume name="Work" href="https://cbs.api.rackspacecloud.com/12934/volumes/23" /> </volumes> </server> </servers>
Example 1.35. Extended server: JSON response
{ "servers": [ { "id": "52415800-8b69-11e0-9b19-734f6af67565", "tenant_id": "1234", "user_id": "5678", "name": "sample-server", "updated": "2010-10-10T12:00:00Z", "created": "2010-08-10T12:00:00Z", "hostId": "e4d909c290d0fb1ca068ffaddf22cbd0", "status": "BUILD", "progress": 60, "accessIPv4" : "67.23.10.132", "accessIPv6" : "::babe:67.23.10.132", "image" : { "id": "52415800-8b69-11e0-9b19-734f6f006e54", "links": [ { "rel": "self", "href": "http://servers.api.openstack.org/v2/1234/images/52415800-8b69-11e0-9b19-734f6f006e54" }, { "rel": "bookmark", "href": "http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f6f006e54" } ] }, "flavor" : { "id": "52415800-8b69-11e0-9b19-734f216543fd", "links": [ { "rel": "self", "href": "http://servers.api.openstack.org/v2/1234/flavors/52415800-8b69-11e0-9b19-734f216543fd" }, { "rel": "bookmark", "href": "http://servers.api.openstack.org/1234/flavors/52415800-8b69-11e0-9b19-734f216543fd" } ] }, "addresses": { "public" : [ { "version": 4, "addr": "67.23.10.132" }, { "version": 6, "addr": "::babe:67.23.10.132" }, { "version": 4, "addr": "67.23.10.131" }, { "version": 6, "addr": "::babe:4317:0A83" } ], "private" : [ { "version": 4, "addr": "10.176.42.16" }, { "version": 6, "addr": "::babe:10.176.42.16" } ] }, "metadata": { "Server Label": "Web Head 1", "Image Version": "2.1" }, "links": [ { "rel": "self", "href": "http://servers.api.openstack.org/v2/1234/servers/52415800-8b69-11e0-9b19-734f6af67565" }, { "rel": "bookmark", "href": "http://servers.api.openstack.org/1234/servers/52415800-8b69-11e0-9b19-734f6af67565" } ], "RS-CBS:volumes": [ { "name": "OS", "href": "https://cbs.api.rackspacecloud.com/12934/volumes/19" }, { "name": "Work", "href": "https://cbs.api.rackspacecloud.com/12934/volumes/23" } ] } ] }
Example 1.36. Extended action: XML response
<?xml version="1.0" encoding="UTF-8"?> <attach-volume xmlns="http://docs.rackspacecloud.com/servers/api/ext/cbs/v1.0" href="https://cbs.api.rackspacecloud.com/12934/volumes/19"/>
Example 1.37. Extended action: JSON respone
{ "RS-CBS:attach-volume":{ "href":"https://cbs.api.rackspacecloud.com/12934/volumes/19" } }
Method | URI | Description |
---|---|---|
GET | /v2/{tenant_id}/extensions | Lists available extensions. |
GET | /v2/{tenant_id}/extensions | Gets details about the specified extension. |