openstack/neutron
Code Issues Proposed changes

API layer documentation

Browse Source 
* 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
This commit is contained in:
Sean M. Collins 2014-03-08 21:11:23 -05:00
parent 12cbf72265
commit 08cf38e86c
1 changed files with 53 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

53
doc/source/devref/api_layer.rst
View File

@ -1,4 +1,57 @@
Neutron WSGI/HTTP API layer 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 <http://legacy.python.org/dev/peps/pep-0333/>`_
Startup
-------
Neutron's WSGI server is started from the `server module <http://git.openstack.org/cgit/openstack/neutron/tree/neutron/server/__init__.py>`_
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 <http://www.slideshare.net/gongys2004/inside-neutron-2>`_ `Yong Sheng Gong: Deep Dive into Neutron <http://www.slideshare.net/gongys2004/inside-neutron-2>`_