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 determine what extensions are available by performing a GET on the /extensions URI. Note that this is a versioned request — that is, an extension available in one API version may not be available in another.
| Verb | URI | Description | |||
| GET | /extensions | List all available extensions | |||
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. Each extension is identified by two unique identifiers, a namespace and an alias. Additionally an extension contains documentation links in various formats.
Example 1.34. Extensions Response: XML
<?xml version="1.0" encoding="UTF-8"?>
<extensions xmlns="http://docs.openstack.org/common/api/v1.0"
xmlns:atom="http://www.w3.org/2005/Atom">
<extension name="Public Image Extension"
namespace="http://docs.rackspacecloud.com/servers/api/ext/pie/v1.0"
alias="RAX-PIE" updated="2011-01-22T13:25:27-06:00">
<description> Adds the capability to share an image with other
users. </description>
<atom:link rel="describedby" type="application/pdf"
href="http://docs.rackspacecloud.com/servers/api/ext/cs-pie-20111111.pdf"/>
<atom:link rel="describedby"
type="application/vnd.sun.wadl+xml"
href="http://docs.rackspacecloud.com/servers/api/ext/cs-pie.wadl"
/>
</extension>
<extension name="Cloud Block Storage"
namespace="http://docs.rackspacecloud.com/servers/api/ext/cbs/v1.0"
alias="RAX-CBS" updated="2011-01-12T11:22:33-06:00">
<description> Allows mounting cloud block storage volumes.</description>
<atom:link rel="describedby" type="application/pdf"
href="http://docs.rackspacecloud.com/servers/api/ext/cs-cbs-20111201.pdf"/>
<atom:link rel="describedby"
type="application/vnd.sun.wadl+xml"
href="http://docs.rackspacecloud.com/servers/api/ext/cs-cbs.wadl"
/>
</extension>
</extensions>
Example 1.35. Extensions Response: JSON
{
"extensions": [
{
"name": "Public Image Extension",
"namespace": "http://docs.rackspacecloud.com/servers/api/ext/pie/v1.0",
"alias": "RAX-PIE",
"updated": "2011-01-22T13:25:27-06:00",
"description": "Adds the capability to share an image with other users.",
"links": [
{
"rel": "describedby",
"type": "application/pdf",
"href": "http://docs.rackspacecloud.com/servers/api/ext/cs-pie-20111111.pdf"
},
{
"rel": "describedby",
"type": "application/vnd.sun.wadl+xml",
"href": "http://docs.rackspacecloud.com/servers/api/ext/cs-pie.wadl"
}
]
},
{
"name": "Cloud Block Storage",
"namespace": "http://docs.rackspacecloud.com/servers/api/ext/cbs/v1.0",
"alias": "RAX-CBS",
"updated": "2011-01-12T11:22:33-06:00",
"description": "Allows mounting cloud block storage volumes.",
"links": [
{
"rel": "describedby",
"type": "application/pdf",
"href": "http://docs.rackspacecloud.com/servers/api/ext/cs-cbs-20111201.pdf"
},
{
"rel": "describedby",
"type": "application/vnd.sun.wadl+xml",
"href": "http://docs.rackspacecloud.com/servers/api/ext/cs-cbs.wadl"
}
]
}
]
}
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.
| Verb | URI | Description | |||
| GET | /extensions/alias |
Get details about a specific extension | |||
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), itemNotFound (404)
Example 1.36. Extension Response: xml
<?xml version="1.0" encoding="UTF-8"?>
<extension xmlns="http://docs.openstack.org/common/api/v1.0"
xmlns:atom="http://www.w3.org/2005/Atom"
name="Public Image Extension"
namespace="http://docs.rackspacecloud.com/servers/api/ext/pie/v1.0"
alias="RS-PIE" updated="2011-01-22T13:25:27-06:00">
<description> Adds the capability to share an image with other
users. </description>
<atom:link rel="describedby" type="application/pdf"
href="http://docs.rackspacecloud.com/servers/api/ext/cs-pie-20111111.pdf"/>
<atom:link rel="describedby" type="application/vnd.sun.wadl+xml"
href="http://docs.rackspacecloud.com/servers/api/ext/cs-pie.wadl"
/>
</extension>
Example 1.37. Extension Response: JSON
{
"extension" : {
"name" : "Public Image Extension",
"namespace" : "http://docs.rackspacecloud.com/servers/api/ext/pie/v1.0",
"alias" : "RS-PIE",
"updated" : "2011-01-22T13:25:27-06:00",
"description" : "Adds the capability to share an image with other users.",
"links" : [
{
"rel" : "describedby",
"type" : "application/pdf",
"href" : "http://docs.rackspacecloud.com/servers/api/ext/cs-pie-20111111.pdf"
},
{
"rel" : "describedby",
"type" : "application/vnd.sun.wadl+xml",
"href" : "http://docs.rackspacecloud.com/servers/api/ext/cs-pie.wadl"
}
]
}
}
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.38 and 1.39
is defined in the RS-CBS namespace.
Actions work in exactly the same manner as illustrated
in Examples 1.40 and 1.41.
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]](../common/images/admon/important.png) | Important |
|---|---|
Applications should be prepared to ignore
response data that contains extension elements. An
extended state should always be treated as an
|
Example 1.38. Extended Server Response: XML
<?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.39. Extended Server Response: JSON
{
"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.40. Extended Action: XML
<?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.41. Extended Action: JSON
{
"RS-CBS:attach-volume" {
"href" : "https://cbs.api.rackspacecloud.com/12934/volumes/19"
}
}
