1.9. Extensions

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]Important

Applications should be prepared to ignore response data that contains extension elements. An extended state should always be treated as an UNKNOWN state if the application does not support the extension. Applications should also verify that an extension is available before submitting an extended request.

 

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"
   }
}

MethodURIDescription
GET/v2/{tenant_id}/extensions

Lists available extensions.

GET/v2/{tenant_id}/extensions

Gets details about the specified extension.

Questions? Discuss on ask.openstack.org
Found an error? Report a bug against this page


loading table of contents...