[openstack-dev] Writing Openstack Nova API extensions

Kevin L. Mitchell kevin.mitchell at rackspace.com
Wed Sep 26 16:06:34 UTC 2012

On Wed, 2012-09-26 at 21:00 +0530, Trinath Somanchi wrote:
> 1. What are Controller and Resource extensions? How do they differ?

OK, so term definition time.  Nova uses the Routes[1] software to map
URI/HTTP method to a function to call.  Routes happens to provide a
short-cut interface for setting up the routes for REST-style calls
(which is what Nova uses); the call is resource()[2].

Now, in Nova's world, a "Resource" is one of these top-level things; it
has operations like index() ("GET <resource>"), show() ("GET
<resource>/<id>"), update() ("PUT <resource>/<id>"), delete() ("DELETE
<resource>/<id>"), etc.  (See the Routes documentation for the full
list.)  A ResourceExtension is an extension that allows creation of one
of these resources, and the "parent" stuff allows you to link that
resource to be under another resource, i.e., "GET <parent>/<resource>"
maps to index(), "GET <parent>/<resource>/<id>" maps to show(), etc.

A ControllerExtension, on the other hand, allows you to extend an
existing resource—usually one of the basic Nova resources
(i.e., /servers).  With this kind of extension, you can add an
"action" (not your current use case, but see below), or you can wrap an
existing (and only an existing!) method of that resource.  This
limitation is why I suggested you should try using a ResourceExtension
for your use case—there's no way to add a new method to an existing
resource without modifying the code that creates that existing resource.

> 2. How do client requests differ for these type of extensions? Can you
> give some examples on this.

Client requests don't differ at all for these types of extensions; it's
the semantics of what they mean.

I should note that I can see a way to use a ControllerExtension to
retrieve metadetails, but you wouldn't be doing GET /servers/metadetail;
you would be doing POST /servers/action, and the body that you POSTed
would convey the request for metadetails.  (You could also use this body
to convey the query parameters.)  This is called an "action", and if you
want to see examples of how this works, check out the admin_actions.py
extension you've already looked at—it defines a whole bunch of actions.

The Nova API system is rather complicated, and the best documentation
for how to modify and extend it is still the code, unfortunately.  I
hope that I've helped you understand it a bit more clearly, but keep in
mind that much of what I've stated here is from memory, so it might be
worth reading the code for yourself to make sure I got it right :)


[1] http://routes.readthedocs.org/en/latest/index.html
[2] http://routes.readthedocs.org/en/latest/restful.html
Kevin L. Mitchell <kevin.mitchell at rackspace.com>

More information about the OpenStack-dev mailing list