← Back to branch summary

~ubuntu-branches/ubuntu/quantal/nova/quantal-proposed

« back to all changes in this revision

Viewing changes to doc/source/devref/addmethod.openstackapi.rst

  • Committer: Bazaar Package Importer
  • Author(s): Chuck Short
  • Date: 2010-12-13 10:17:01 UTC
  • mto: This revision was merged to the branch mainline in revision 8.
  • Revision ID: james.westby@ubuntu.com-20101213101701-txhhqbzsxw4avnxv
Tags: upstream-2011.1~bzr456
Import upstream version 2011.1~bzr456

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/source/devref/addmethod.openstackapi.rst
 
1
..
 
2
      Copyright 2010 OpenStack LLC 
 
3
      All Rights Reserved.
 
4
 
 
5
      Licensed under the Apache License, Version 2.0 (the "License"); you may
 
6
      not use this file except in compliance with the License. You may obtain
 
7
      a copy of the License at
 
8
 
 
9
          http://www.apache.org/licenses/LICENSE-2.0
 
10
 
 
11
      Unless required by applicable law or agreed to in writing, software
 
12
      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 
13
      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 
14
      License for the specific language governing permissions and limitations
 
15
      under the License.
 
16
 
 
17
Adding a Method to the OpenStack API
 
18
====================================
 
19
 
 
20
The interface is a mostly RESTful API. REST stands for Representational State Transfer and provides an architecture "style" for distributed systems using HTTP for transport. Figure out a way to express your request and response in terms of resources that are being created, modified, read, or destroyed.
 
21
 
 
22
Routing
 
23
-------
 
24
 
 
25
To map URLs to controllers+actions, OpenStack uses the Routes package, a clone of Rails routes for Python implementations. See http://routes.groovie.org/ fore more information.
 
26
 
 
27
URLs are mapped to "action" methods on "controller" classes in nova/api/openstack/__init__/ApiRouter.__init__ .
 
28
 
 
29
See http://routes.groovie.org/manual.html for all syntax, but you'll probably just need these two:
 
30
   - mapper.connect() lets you map a single URL to a single action on a controller.
 
31
   - mapper.resource() connects many standard URLs to actions on a controller.
 
32
 
 
33
Controllers and actions
 
34
-----------------------
 
35
 
 
36
Controllers live in nova/api/openstack, and inherit from nova.wsgi.Controller.
 
37
 
 
38
See nova/api/openstack/servers.py for an example.
 
39
 
 
40
Action methods take parameters that are sucked out of the URL by mapper.connect() or .resource().  The first two parameters are self and the WebOb request, from which you can get the req.environ, req.body, req.headers, etc.
 
41
 
 
42
Serialization
 
43
-------------
 
44
 
 
45
Actions return a dictionary, and wsgi.Controller serializes that to JSON or XML based on the request's content-type.
 
46
 
 
47
If you define a new controller, you'll need to define a _serialization_metadata attribute on the class, to tell wsgi.Controller how to convert your dictionary to XML.  It needs to know the singular form of any list tag (e.g. <servers> list contains <server> tags) and which dictionary keys are to be XML attributes as opposed to subtags (e.g. <server id="4"/> instead of <server><id>4</id></server>).  
 
48
 
 
49
See nova/api/openstack/servers.py for an example.
 
50
 
 
51
Faults
 
52
------
 
53
 
 
54
If you need to return a non-200, you should
 
55
return faults.Fault(webob.exc.HTTPNotFound())
 
56
replacing the exception as appropriate.