Building With the Twitter API: Managing Lists

Final product image
What You'll Be Creating

This is part two of our Twitter List API tutorial within our broader Twitter API series. In this tutorial, we'll walk through building List features with the API. Code samples are provided in the Github repository. Installation instructions are described in more detail here (be sure to use the repository provided in this tutorial and not the initial Birdcage repository listed on that page).

Overview of the Twitter List API

Again, there are roughly 19 APIs for Twitter Lists, divided into three major areas:

Let's begin with integrating some of the basic features of List API development.

Creating a List

When you load Birdcage, you'll see the Manage Lists page. Click the Create a List option in the right sidebar menu.

Twitter List API Manage Lists empty

The Create a List form will be displayed. I'm going to create a list for tracking Seattle journalists on Twitter:

Twitter List API Create a List

Here's the Create code in TwitterlistController.php. It handles code for displaying the form and, after the form is posted, code for processing:

You can read documentation for the Twitter Lists/Create API here.

Once the form is submitted, you'll see something like this:

Twitter List API Manage Twittert Lists after Create

Importing Members to a List

One of the most frustrating limitations of the Twitter List user interface is how difficult it is to add members. You have to visit each member and add them individually to your lists—the process is very convoluted and slow.

We're going to implement a feature to subscribe a comma-separated list of Twitter accounts.

In the list view, if you click on the Manage List icon to the right of Seattle Journalists, you'll see the View List page:

Twitter List API View List Members empty

Click on Import members in the right sidebar menu. Then, type in the list of Twitter accounts you wish to add to this list:

Twitter List API Import Twitter Accounts to List

Let's review the code that uploads the members to Twitter. The code for displaying the form above begins in ListMemberController.php:

In the ListMember.php model, the import code looks as follows. We use preg_split to convert the list of accounts to an array. Then, for each account, we fetch information about the account at Users/Show and post the Twitter ID to Lists Member Create.

After submitting the members, you'll see something like this:

Twitter List API View List Members

The tbd represents a user that isn't already in our database; the profile information will be fetched (hydrated) in the background later.

On Twitter, you'll see something like this:

Twitter List API List Member View at Twitter

Synchronizing Lists

Now that we've created a list, let's fetch the lists that already exist in our account so that we can manage them from our console. Again, from the Manage Lists menu, click Synchronize Lists.

Twitter List API Manage Lists

The sync action is coded in TwitterlistController.php:

The TwitterList.php model sync operation is relatively sophisticated, as shown below. First, the sync model loops through all of the accounts you've configured and calls the syncOne account for lists.

SyncOne calls fetch Lists/Ownerships in the API to find all the lists owned by each account. 

However, rather than try to fetch the members for the list in real time, which would likely time out, it creates a background action to fetch the members for a given list.

The background cron task invokes the Action.php model which calls getListMembership for one list at a time.

When the task runs, it invokes the TwitterList.php model's getMemberships method. This method uses cursoring to page through member records without timing out or hitting rate limits. The last cursor is stored in the Action table so that the next background invocation can continue adding members where it left off previously. 

You should see something like this when the operation completes:

Twitter List API Manage Lists

Once the background tasks complete, you'll see members for each list like this:

Twitter List API View List Members

What's Next?

I hope you've enjoyed this Twitter List API series thus far. I'd like to hear your suggestions of favorite API scenarios and feature requests; please post them in the comments.

If you have any questions or suggestions, please post them in the comments. If you'd like to keep up on my future Tuts+ tutorials and other series, please visit my instructor page or follow @reifman.

Related Links



Related Articles