Revision as of 20:23, 27 October 2011

Writing Request Extensions

This page is, at present, sketchy notes on how to create a new "request" extension (an extension applying to existing nova API operations, such as showing information about a server). The primary emphasis is using XML templates, which were created as a means of enabling the request extensions to actually exist in the first place.

Preliminaries

First, we'll discuss the creation of an extension in general. Extensions to be distributed with nova should live in the nova/api/openstack/contrib directory, and the class describing the extension (which we'll get to shortly) should have a name identical to that of the module, with the first letter capitalized; that is, if your module is "admin_actions.py", then your class should be named "Admin_actions" (yes, with the underscore; this is documentation of existing practice, not an approval of it). This naming convention is only necessary for extensions that should always be active; optional extensions should not live in this directory and can have any desired naming scheme. To load these extensions, specify the dotted path to the module as an argument to the `--osapi_extension` flag. (This flag may be given multiple times, to specify additional extensions.)

Now, on to the structure of an extension. An extension is simply a class; it is recommended that it extend `nova.api.openstack.extensions.ExtensionDescriptor`, but this is not required. What is required is that the class have a doc string, which will be used as the description of the extension sent to the user upon request. Additionally, the following four class attributes must be present:

name 

The name of the extension. This need not match the class name.

alias 

An alias for the extension. This is used as the namespace prefix on XML elements.

namespace 

An XML namespace declaration, typically a URL to a document describing the extension.

updated 

A complete ISO 8601-formatted date and time, with timezone, indicating the last update time of the extension. This is used for versioning. An example value would be "2011-10-27T15:00:00-0500", corresponding to 3 PM in US Central Daylight Time on October 27, 2011.

The extension must have an `init()` method taking a single argument; it should call the `register()` method of that argument, passing it `self`. This is provided by `nova.api.openstack.extensions.ExtensionDescriptor`:

#!highlight python
def __init__(self, ext_mgr):
    ext_mgr.register(self)

The only other thing the extension requires is at least one of the following three methods:

get_resources() 

Returns a list of `nova.api.openstack.extensions.ResourceExtension` objects describing new resources. A resource extension introduces a new resource (i.e., a new URL component). This document does not describe these further.

get_actions() 

Returns a list of `nova.api.openstack.extensions.ActionExtension` objects describing new actions. An action extension introduces a new action defined on the `action` endpoint of an existing resource. This document does not describe these further.

get_request_extensions() 

Returns a list of `nova.api.openstack.extensions.RequestExtension` objects describing extensions to existing resources.

Methods not needed to implement the extension are not required to be present. The `nova.api.openstack.extensions.ExtensionDescriptor` class provides default implementations of these methods which simply return empty lists, but it is legal to omit them if you are not extending that class.