launchpadblog

The 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.

This entry was posted by Leonard Richardson on Wednesday, April 29th, 2009 at 9:32 pm and is filed under General. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.