nova/api-guide/source/extensions.rst

Extensions

The OpenStack Compute API v2.0 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 because an unavailable extension issues an itemNotFound (404) response.

Extensions may define new data types, parameters, actions, headers, states, and resources. In XML, additional elements and attributes can be defined. These elements must be defined in the namespace for the extension. In JSON, the alias must be used. The volumes element is defined in the RS-CBS namespace. 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 might be in the RS-PIE:PrepareShare state.

Important

Applications should 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: 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: Extended action: JSON response

{
   "RS-CBS:attach-volume":{
      "href":"https://cbs.api.rackspacecloud.com/12934/volumes/19"
   }
}