Launchpad’s web service code released as standalone libraries
Wednesday, April 29th, 2009The last time I posted to this blog I was describing a sprint in Montreal, where we were working on refactoring the web service code and moving it from Launchpad to a standalone library. Several weeks of work later, we’re done. You can now create your own web service using the same techniques we use in Launchpad.
The library is lazr.restful, and there’s a companion client library called lazr.restfulclient. They’re also on PyPI (restful
, restfulclient
). The place to discuss these libraries is the lazr-users mailing list.
I’ll show you lazr.restful
first. If you just want to use the package, and you have easy_install, try “easy_install lazr.restful“. You can also download the tarball and use “python setup.py install“ on it. Or you can get check out the source code:
$ bzr branch lp:lazr.restful mybranch $ cd mybranch $ python bootstrap $ python bin/buildout $ python bin/test
The test
command starts up the web service defined in src/lazr/restful/example
and puts it through its paces with simulated HTTP requests. The example web service shows how to use Python decorators to turn Zope interfaces into a web service with the same features as Launchpad’s web service. Just as an example, here’s what a normal Zope interface might look like:
class IPerson(Interface): first_name = TextLine(title=u"First name", required=True) last_name = TextLine(title=u"Last name", required=True)
Here’s what it would look like with lazr.restful
annotations:
class IPerson(Interface): export_as_webservice_entry(plural_name='people') first_name = exported(TextLine(title=u"First name", required=True)) last_name = exported(TextLine(title=u"Last name", required=True))
lazr.restful
will inspect that interface and know that you’re defining an ‘entry’ type resource, with each entry containing two bits of data. It’ll publish a WADL file describing that interface. Clients will be able to make GET, PUT, and PATCH requests to the ‘person’ resources to manipulate your application data.
lazr.restful
provides annotations for every web service feature you see in Launchpad: entries, collections, hosted files, named operations, and so on. It even has some features that aren’t used by Launchpad yet, like the ability to make entries respond to DELETE requests.
lazr.restfulclient
is the client side. We took almost all the code out of launchpadlib
and made a generic client that will run against any lazr.restful
service.
The same bootstrap
–buildout
–test
cycle that worked for lazr.restful
also works for lazr.restfulclient
. The test
command will start up the web service from lazr.restful
, and manipulate it with Pythonic launchpadlib-like commands instead of fake HTTP requests. Given a ‘person’ resource like the one defined in the example above, you could run this code in lazr.restfulclient
.
person_resource.first_name = "new first name" person_resource.lp_save()
Before long we’ll be removing almost all the code from launchpadlib
leaving only the OAuth handling and some Launchpad-specific information. We’re also working to make it easier to use lazr.restful
with standard WSGI applications, so you don’t have to know as much Zope.