From 27c79e67dbe65e22d3c80237259364eee7001495 Mon Sep 17 00:00:00 2001 From: "Sean M. Collins" Date: Sat, 8 Mar 2014 21:11:23 -0500 Subject: [PATCH] API layer documentation * Discuss the WSGI layer of Neutron * Describe the startup code that creates the WSGI application * Briefly discuss the URL routing and resource creation Change-Id: Id82a2a5679d7e29c0a19d1a20942a9249946b011 --- doc/source/devref/api_layer.rst | 53 +++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/doc/source/devref/api_layer.rst b/doc/source/devref/api_layer.rst index 63cb66b729..a3e5e7f695 100644 --- a/doc/source/devref/api_layer.rst +++ b/doc/source/devref/api_layer.rst @@ -1,4 +1,57 @@ Neutron WSGI/HTTP API layer =========================== +This section will cover the internals of Neutron's HTTP API, and the classes +in Neutron that can be used to create Extensions to the Neutron API. + +Python web applications interface with webservers through the Python Web +Server Gateway Interface (WSGI) - defined in `PEP 333 `_ + +Startup +------- + +Neutron's WSGI server is started from the `server module `_ +and the entry point `serve_wsgi` is called to build an instance of the +`NeutronApiService`_, which is then returned to the server module, +which spawns a `Eventlet`_ `GreenPool`_ that will run the WSGI +application and respond to requests from clients. + + +.. _NeutronApiService: http://git.openstack.org/cgit/openstack/neutron/tree/neutron/service.py + +.. _Eventlet: http://eventlet.net/ + +.. _GreenPool: http://eventlet.net/doc/modules/greenpool.html + +WSGI Application +---------------- + +During the building of the NeutronApiService, the `_run_wsgi` function +creates a WSGI application using the `load_paste_app` function inside +`config.py`_ - which parses `api-paste.ini`_ - in order to create a WSGI app +using `Paste`_'s `deploy`_. + +The api-paste.ini file defines the WSGI applications and routes - using the +`Paste INI file format`_. + +The INI file directs paste to instantiate the `APIRouter`_ class of +Neutron, which contains several methods that map Neutron resources (such as +Ports, Networks, Subnets) to URLs, and the controller for each resource. + + +.. _config.py: http://git.openstack.org/cgit/openstack/neutron/tree/neutron/common/config.py + +.. _api-paste.ini: http://git.openstack.org/cgit/openstack/neutron/tree/etc/api-paste.ini + +.. _APIRouter: http://git.openstack.org/cgit/openstack/neutron/tree/neutron/api/v2/router.py + +.. _Paste: http://pythonpaste.org/ + +.. _Deploy: http://pythonpaste.org/deploy/ + +.. _Paste INI file format: http://pythonpaste.org/deploy/#applications + +Further reading +--------------- + `Yong Sheng Gong: Deep Dive into Neutron `_