lazr.restful

lazr.restful is a library for publishing Python objects through a RESTful web service. To tell lazr.restful which objects you want exposed and how, you annotate your existing Zope interfaces.

The WSGI example web service

The example web service in src/lazr/restful/example/wsgi/ is the best place to start understanding lazr.restful. It’s a very simple web service that uses a subset of lazr.restful’s features and can be run as a standalone WSGI application. An explanation of the code can be found in src/lazr/restful/example/wsgi/README.txt

The full example web service

To understand all of lazr.restful, you should look at the web service defined in src/lazr/restful/example/base/. It defines a simple application serving information about cookbooks and recipes. The interfaces (interfaces.py) are annotated with lazr.restful decorators that say which fields and methods to publish from IRecipe, ICookbook, and so on. The implementations of those interfaces are in root.py.

The machinery of lazr.restful takes the decorators in interfaces.py, and generates an interface that maps incoming HTTP requests to operations on the actual objects defined in root.py. You don’t have to do any HTTP server programming to get it to work (though at the moment you do have to know a fair amount about Zope).

You can test the example web service by running bin/test. The doctests in src/lazr/restful/example/base/tests use a fake httplib2 connection to simulate HTTP requests to the web service. You can watch the tests make GET, PUT, POST, PATCH, and DELETE requests to the web service. Start with root.txt.

Other code

Two other pieces of code might be of interest when you’re starting out.

  • declarations.py contains all the Python decorators. docs/webservice-declarations.txt shows how to use them.

  • docs/webservice.txt shows an example of a webservice that creates Entry and Collection classes directly rather than generating them with the declarations. If you want to use lazr.restful without using zope.schema, this is the test to look at.

Other Documents