Building With the Twitter API: OAuth, Reading and Posting

Final product image
What You'll Be Creating

This post is the second of a three part series on using the Twitter API. If you missed part one, you can read it here.

Authenticating With Twitter via OAuth

Birdcage uses a Yii extension called Yii Twitter by Will Wharton, which makes use of the open-source PHP OAuth Twitter library by Abraham Williams.

I place the extension in the Yii tree under /app/protected/extensions/yiitwitteroauth. In Yii, you configure extension properties in the main.php configuration file like so:

Normally, I'd load these settings from my Yii .ini file, but to make the Birdcage setup simpler, I'm configuring the application keys from the UserSettings model. I've extended YiiTwitter.php to load the default user's application keys during initialization:

Once you've installed and configured the application settings, you'll need to visit the Accounts menu and click Add Your Twitter Account

Mange Accounts in the Birdcage application

When you click on the Twitter icon, it executes the Connect method of the Birdcage Twitter controller:

This will take you back to Twitter via OAuth to authenticate your Twitter account:

Twitter OAuth Challenge Screen

Once you've logged in, Twitter will ask you to authorize the Birdcage application:

Authorize app for Twitter API

Twitter will return the browser to your callback URL, our Twitter Controller Callback method. It will save your Twitter user OAuth token and secret in the account table:

Now, Birdcage is ready to begin making requests for Twitter data via the API on behalf of your user account.

As you'll see ahead, a simple call with the tokens allows access to the API:

Processing Tweets in the Background

For part two of our tutorial, we're using the Twitter REST API. Part three will delve into the real-time, always-on Streaming API:

Using the Twitter REST API

Retrieving Twitter Timelines

Twitter timelines are an ever-expanding stack of tweets, so monitoring activity is a bit more complicated than your average REST API. You can learn more about the unique problem Twitter timelines present here. Essentially, as you're trying to read the timeline history, more tweets are being added all the time:

The Ever Expanding Twitter Timeline

Twitter provides a relatively simple way to manage this. You can follow the code that performs this in Birdcage's Tweet model, getRecentTweets().

First, we look up the highest (most recent) tweet_id in our database, and return an incremented value:

Then, we request some number (e.g. 100) of tweets since the highest previously processed one. The Twitter API recognizes the since_id as a pointer to the place in the timeline you wish to start retrieving from. It will return all the tweets more recent than since_id. In the example below, we're querying the REST API statuses/home_timeline method. The home timeline is what a user sees on their main Twitter screen.

It's also important to check if we've been rate limited by Twitter. Each application-user request is allowed 180 requests to a user's home timeline per 15-minute window—but rate limits vary by activity, so you're programming mileage may vary.

For each tweet received, we call our Parse() method to process the data and store it in our various database tables. During the process, we track the oldest/lowest tweet_id that we've received from Twitter:

The parse method adds the referenced Twitter user information and then the tweet itself. There's more detail in the Parse.php model.

Then, we continue to request blocks of tweets using the lowest ID from the last request as a max_id parameter which we send to Twitter. We make these subsequent requests using the since_id of the tweet we began with and the max_id from the last oldest tweet we retrieved.

So, for example, as newer tweets come in, we don't see them—because Twitter is only sending us tweets since the initial highest tweet_id (since_id) from our database. We'll have to come back later to get newer tweets, which are higher than our initial since_id.

It's important to note that we do not receive an infinite number of older tweets. Twitter returns to us only the number of tweets we request that are older than the previous low ID or (max_id in our next call).

Once you get used to the model and nomenclature, it's quite simple.

While there is a Fetch menu command which will run this operation, we also configure a cron job to call our DaemonController method every five minutes:

This in turn calls our getStreams method which performs the operations described above (note, the streams' functionality will be described in part three of this series):

The end result looks something like this:

Birdcage statuses home_timeline via Twitter API

One time I did run into some Twitter API reliability problems. You can check the status of the Twitter API services here.

Posting a Tweet

Posting tweets to your Twitter account is actually quite straightforward. We just need to make use of the statuses/update REST method. It takes a bit more work to perform accurate character counts. 

Twitter resolves all URLs into shortcuts, so all URLs are counted as 20 characters. I needed JavaScript that would count characters and adjust for any URL by 20 characters regardless of the length of a URL. I settled on a combination of jQuery and JavaScript solutions, which I'll detail below.

I chose to create a model specifically for composing tweets called Status.php. This made it easier to work with Yii to generate forms for posting to the API. 

When you click on Compose in the Birdcage menu, it will take you to the Compose method of the StatusController:

This will load the HTML form for creating a Status item. Check out the _form.php in /app/protected/views/status/.

First, I'll load several jQuery and JavaScript libraries for character counting:

I used a combination of the jQuery simplyCountable plugin, twitter-text.js (a JavaScript-based Twitter text-processing script) and a script that did the heavy lifting of URL adjustments: twitter_count.js.

The following code then creates the remainder of the compose form and activates the character counting scripts:

The result looks like this:

The Birdcage Compose a Tweet PHP Twitter API Example

When the tweet is saved, it executes this code in the StatusController—which posts the resulting tweet_text to Twitter via OAuth:

Next Steps

In this part of the series, we've reviewed how to authenticate with the Twitter API via OAuth, how to query for ranges of tweets in the user's timeline, and how to count characters and post tweets via the API. I hope you've found this useful.

Part three will cover using the Twitter Streaming API and the open source Phirehose streaming implementation.

Please post any comments, corrections, or additional ideas below. You can browse my other Tuts+ tutorials on my author page or follow me on Twitter @reifman.



Related Articles