Tuesday, May 25, 2010

A plan of attack on the buzz API using Python + REST

So, as of last Wednesday, the Buzz API is out. Right now, things are early stage still. You can do things, but there are not a lot of refined examples to help you along, and the client libraries for popular web programming languages like Python are not yet fully complete.

By counter, examples for the REST endpoints are more fully developed, and I've decided to just use those. Directly using the REST endpoints in python is a little more difficult because it requires you to do things like marshall your requests into a non-python data format such as xml or json and decode all responses from said format. You also potentially have to handle things like authentication using the oauth protocol. Fortunately for the intrepid, there are a few resources that can shed some light on how to proceed. I'll list them here:

  • First is the documentation for the buzz REST API. It gives both an overview of the API's philosophy and concrete examples to illustrate it. Often, you can just execute the examples in the address bar of the chrome web browser to get an idea of the kind of information you'll get back.
  • Second is oacurl. This is a java command line utility that's pretty easy to install on most unix-like systems (I'm on mac os x). It's an easy way to make requests of the API and see the raw response it sends back. When required, oacurl allows you to easily execute actions that require authentication via oauth. The cookbook is invaluable. Executing those examples will give you more than one aha! moment.
  • Third is the buzz bingo example written in Python and presented last week at Google I/O. The beauty of this example is that it follows the REST strategy I'm laying out for myself here. In other words, it can act as a blueprint in Python for some of the features and hurdles I'll need to overcome when using REST.
  • The python packages httplib2 and simplejson. The main advantage is that these are in widespread use. Further, I myself have used them, so getting reacquainted should not be too bad. httplib2 facilitates connecting over http to REST endpoints. simplejson is a python package for decoding json.

My plan of attack going forward

My guess is that the developers of the buzz API expect the modal programmer using it to be coding some sort of web app which will ask the user's permission to access data. I plan to get there at some point, but first I'm going to see if I can pull public data for a few users and see if I can interrelate it. That will allow me to cut out a lot of complexity, like hosting the app on the web or needing to manage authentication.