Extensions

The OpenStack Identity 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		Returns a list of available extensions

Normal Response Code(s):200, 203

Error Response Code(s): badRequest (400), identityFault (500), serviceUnavailable(503)

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.23. 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="Reset Password Extension"
        namespace="http://docs.rackspacecloud.com/identity/api/ext/rpe/v1.0"
        alias="RS-RPE"
        updated="2011-01-22T13:25:27-06:00">

        <description>
            Adds the capability to reset a user's password.  The user is
            emailed when the password has been reset.
        </description>

        <atom:link rel="describedby"
                   type="application/pdf"
                   href="http://docs.rackspacecloud.com/identity/api/ext/identity-rpe-20111111.pdf"/>
        <atom:link rel="describedby"
                   type="application/vnd.sun.wadl+xml"
                   href="http://docs.rackspacecloud.com/identity/api/ext/identity-rpe.wadl"/>
    </extension>
    <extension
        name="User Metadata Extension"
        namespace="http://docs.rackspacecloud.com/identity/api/ext/meta/v2.0"
        alias="RS-META"
        updated="2011-01-12T11:22:33-06:00">
        <description>
            Allows associating arbitrary metadata with a user.
        </description>

        <atom:link rel="describedby"
                   type="application/pdf"
                   href="http://docs.rackspacecloud.com/identity/api/ext/identity-meta-20111201.pdf"/>
        <atom:link rel="describedby"
                   type="application/vnd.sun.wadl+xml"
                   href="http://docs.rackspacecloud.com/identity/api/ext/identity-meta.wadl"/>
    </extension>
</extensions>

Example 1.24. Extensions Response: JSON

{
    "extensions":[{
            "name": "Reset Password Extension",
            "namespace": "http://docs.rackspacecloud.com/identity/api/ext/rpe/v2.0",
            "alias": "RS-RPE",
            "updated": "2011-01-22T13:25:27-06:00",
            "description": "Adds the capability to reset a user's password. The user is emailed when the password has been reset.",
            "links":[{
                    "rel": "describedby",
                    "type": "application/pdf",
                    "href": "http://docs.rackspacecloud.com/identity/api/ext/identity-rpe-20111111.pdf"
                },
                {
                    "rel": "describedby",
                    "type": "application/vnd.sun.wadl+xml",
                    "href": "http://docs.rackspacecloud.com/identity/api/ext/identity-rpe.wadl"
                }
            ]
        },
        {
            "name": "User Metadata Extension",
            "namespace": "http://docs.rackspacecloud.com/identity/api/ext/meta/v2.0",
            "alias": "RS-META",
            "updated": "2011-01-12T11:22:33-06:00",
            "description": "Allows associating arbritrary metadata with a user.",
            "links":[{
                    "rel": "describedby",
                    "type": "application/pdf",
                    "href": "http://docs.rackspacecloud.com/identity/api/ext/identity-meta-20111201.pdf"
                },
                {
                    "rel": "describedby",
                    "type": "application/vnd.sun.wadl+xml",
                    "href": "http://docs.rackspacecloud.com/identity/api/ext/identity-meta.wadl"
                }
            ]
        }
    ],
    "extensions_links":[]
}

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`		Return details of a single extension

Normal Response Code(s):200, 203

Error Response Code(s): itemNotFound (404), badRequest (400), identityFault (500), serviceUnavailable(503)

This operation does not require a request body.

Example 1.25. 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="User Metadata Extension"
           namespace="http://docs.rackspacecloud.com/identity/api/ext/meta/v2.0"
           alias="RS-META"
           updated="2011-01-12T11:22:33-06:00">

    <description>
        Allows associating arbitrary metadata with a user.
    </description>

    <atom:link rel="describedby"
               type="application/pdf"
               href="http://docs.rackspacecloud.com/identity/api/ext/identity-meta-20111201.pdf"/>
    <atom:link rel="describedby"
               type="application/vnd.sun.wadl+xml"
               href="http://docs.rackspacecloud.com/identity/api/ext/identity-meta.wadl"/>

</extension>

Example 1.26. Extensions Response: JSON

{
  "extension": {
    "name": "User Metadata Extension",
    "namespace": "http://docs.rackspacecloud.com/identity/api/ext/meta/v2.0",
    "alias": "RS-META",
    "updated": "2011-01-12T11:22:33-06:00",
    "description": "Allows associating arbritrary metadata with a user.",
    "links": [
      {
        "rel": "describedby",
        "type": "application/pdf",
        "href": "http://docs.rackspacecloud.com/identity/api/ext/identity-meta-20111201.pdf"
      }, {
        "rel": "describedby",
        "type": "application/vnd.sun.wadl+xml",
        "href": "http://docs.rackspacecloud.com/identity/api/ext/identity-cbs.wadl"
      }
    ]
  }
}

Extensions can 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.27 and 1.28 is defined in the RS-META namespace. Extended headers are always prefixed with X- followed by the alias and a dash: (X-RS-META-HEADER1). Parameters must be prefixed with the extension alias followed by a colon.

	Important
	Applications should be prepared to ignore response data that contains extension elements. Also, applications should also verify that an extension is available before submitting an extended request.

Example 1.27. Extended User Response: XML

<?xml version="1.0" encoding="UTF-8"?>
<user xmlns="http://docs.openstack.org/identity/api/v2.0"
      enabled="true" email="[email protected]"
      id="u1000" username="jqsmith">
    <metadata
        xmlns="http://docs.rackspacecloud.com/identity/api/ext/meta/v2.0">
        <meta key="MetaKey1">MetaValue1</meta>
        <meta key="MetaKey2">MetaValue2</meta>
    </metadata>
</user>

Example 1.28. Extended User Response: JSON

{
  "user": {
    "id": "1000",
    "username": "jqsmith",
    "email": "[email protected]",
    "enabled": true,
    "RS-META:metadata": {
      "values": {
        "MetaKey1": "MetaValue1",
        "MetaKey2": "MetaValue2"
      }
    }
  }
}

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

Legal notices