RESTful and OAuth-Cladded APIs

The year 2010 will be remembered by some as the transition period in which Twitter started to become “all grown up.” Basic HTTP authentication got replaced with OAuth^[24] (more on this shortly), documentation improved, and API statuses became transparent, among other things. Twitter search APIs that were introduced with Twitter’s acquisition of Summize collapsed into the “traditional” REST API, while the streaming APIs gained increasing use for production situations. If Twitter were on the wine menu, you might pick up the 2010 bottle and say, “it was a good year—a very good year.” All that said, there’s a lot of useful information tucked away online, and this chapter aims not to reproduce any more of it than is absolutely necessary.

Most of the development in this chapter revolves around the social graph APIs for getting the friends and followers of a user, the API for getting extended user information (name, location, last tweet, etc.) for a list of users, and the API for getting tweet data. An entire book of its own (literally) could be written to explore additional possibilities, but once you’ve learned the ropes, your imagination will have no problems taking over. Plus, certain exercises always have to be left for the “interested reader,” right?

The Python client we’ll use for Twitter is quite simply named twitter (the same one we’ve already seen at work in Chapter 1). It provides a minimal wrapper around Twitter’s RESTful web services. There’s very little documentation about this module because you simply construct requests in the same manner that the URL is pieced together in Twitter’s online documentation. For example, a request from the terminal that retrieves Tim O’Reilly’s user info simply involves dispatching a request to the /users/show resource as a curl command, as follows:

$ curl 'http://api.twitter.com/1/users/show.json?screen_name=timoreilly'

There are a couple of subtleties about this request. First, Twitter has a versioned API, so the appearance of /1 as the URL context denotes that Version 1 of the API is in use. Next, a user_id could have been passed in instead of a screen_name had one been available. The mapping of the curl command to the equivalent Python script in Example 4-1 should be obvious.

# -*- coding: utf-8 -*-

import twitter
import json

screen_name = 'timoreilly'
t = twitter.Twitter(domain='api.twitter.com', api_version='1')
response = t.users.show(screen_name=screen_name)
print json.dumps(response, sort_keys=True, indent=4)

In case you haven’t reviewed Twitter’s online docs yet, it’s probably worthwhile to explicitly mention that the /users/show API call does not require authentication, and it has some specific peculiarities depending on whether a user has “protected” his tweets in the privacy settings. The /users/lookup API call is very similar to /users/show except that it requires authentication and allows you to pass in a comma-separated list of screen_name or user_id values so that you can perform batch lookups. To obtain authorization to use Twitter’s API, you’ll need to learn about OAuth, which is the topic of the next section.