Difference between revisions of "C4LN 2012: Intro to the Twitter API"

Latest revision as of 16:27, 24 May 2012

Presenter: Rick Scott - @shadowspar

API Overview

https://dev.twitter.com/docs is the main documentation area -- you'll spend a lot of time here =)

Other useful things:

• https://dev.twitter.com/ is API central. Amongst other things, it links to:
  • API Status
  • API Known Issues
  • API blog, discussion, etc etc

Parts

• the REST API
• the Streaming API
• the Search API

REST API

• query→response based access
• the mainstay of the API; the first part of it you'll want to be concerned with, and the part you'll likely use most

Streaming API

• aka drinking from the firehose =)
• persistent connection
• push-based communication w/ v.high ratelimit (1% of all tweets)

Search API

• just like it says on the tin
• also trending topics

Find your library

https://dev.twitter.com/docs/twitter-libraries has a good list

• Perl: Net::Twitter
• Python: tweepy and many others
• Ruby: twitter rubygem and others

Creating a new app

BEFORE creating an app: Bot-specific stuff

If you're going to have a separate twitter account for your bot, the best thing to do is to create that account before you create your app. Then create your new app under under the bot's account. This will simplify doing the OAuth dance below.

First steps to create an app

• https://dev.twitter.com/apps/new
• sign in with your twitter (bot's) account
• fill out basic info about your app
• agree to be a good citizen, as detailed below

Huzzah! You have your very own app!

A brief segue into OAuth

http://hueniverse.com/oauth/guide/intro/

OAuth metaphor: valet key to your car

• lets an app act on behalf of a user when dealing with some service
• lets a user give an app specific permissions to interact with a service on their behalf

Roles in OAuth:

• consumer (client) -- your app
• service provider (server) -- Twitter
• user (resource owner) -- user

Credentials

• consumer credentials (consumer key & consumer secret)
• access credentials (access token & access secret)
• (also request token & secret)

OAuth workflow:

• user goes to server and says they'd like to authorize application X to do action Y
• server generates access token which represents the combination of the specific app & the specific user & the specific level of access the user has granted to that app
• user feeds the access token to the app
• the app can then present the access token to the server (in combination with its consumer credentials) and be permitted to do whatever's been authorized

Set up the App

After you've set up your app, you receive your OAuth consumer keys for the app:

• consumer_key
• consumer_secret

The first thing you're going to want to do is go into your app settings and set the correct level of access that your app is going to request from users. This is under the Settings tab:

• Application type:
  • Read
  • Read/Write
  • Read/Write/Access DMs

You are probably going to want one of the latter two. Which one depends on whether or not your app is going to work with DMs (direct messages) or not.

You can also fill in the rest of the self-explanatory fields in the Details and Settings tabs as you like (organization, etc).

Authorize the App on your Bot's Account

While still logged in under the bot's account, navigate to the app's page and generate your access token:

Details tab → Your Access Token *click*

Now your bot's twitter account has granted authorization to your app to act on its behalf. You'll that the relevant access token credentials have been created:

• access_token
• access_token_secret

Getting started on the code

Each Twitter API library is going to have its own way to get initialized and set up. Usually it's going to start with creating an object to represent your connection to Twitter and feeding it ALL THE KEYS.

   my $twitter = Net::Twitter->new(
       traits => [qw/API::REST OAuth/],
       consumer_key => $conf{'consumer_key'},
       consumer_secret => $conf{'consumer_secret'},
       access_token => $conf{'access_token'},
       access_token_secret => $conf{'access_token_secret'},
   );

...and then you'll be able to use the library methods to do the things that you might want to do.

Rules of the Road

General Rules of Conduct and TOS

• https://dev.twitter.com/terms/api-terms
• https://support.twitter.com/articles/76915 - automation rules and best practices

Rate limits

Twitter has a very, very load/performance-centric outlook on the world because of the massive amounts of data and requests they deal with. If you don't play by the rules, twitter has absolutely no hesitation in going NO SOUP FOR YOU.

• REST api is limited to...
  • 350/reqs per hour per signed-in account
  • 150/reqs per hour per anonymous IP address

Things that do count against your limit

• pretty much anything that involves hitting the REST API: fetching tweets from your timeline, fetching user profiles, fetching your @-replies, getting a list of followers, whatever.

Things that do not count against your limit (but see below)

• publishing status updates (sending tweets)
• sending direct messages
• following and unfollowing
• checking the rate limit by querying account/rate_limit_status
  • it can change, though nowadays it rarely does
  • note also that you get three headers describing how quickly you're nomming through your ratelimit as part of every REST API reply, eg:
    • X-RateLimit-Limit: 350
    • X-RateLimit-Remaining: 350
    • X-RateLimit-Reset: 1277485629

Other, service-specific limits

• 1,000 tweets per day
• 250 DMs per day
• follow limits: +1,000 per day plus additional monitoring once you hit 2,000 followed users

Other gotchas

• Repeated tweets
  • You can't post a tweet that's an exact duplicate of any of your last few tweets. "Whoops! You already tweeted that!"
• Failed requests
  • Twitter does crap out every now and again due to load or whatever other reason, so you need to watch for failures and catch the resulting exceptions. [500/502/503/504]

• HTTP responses / error codes are meaningful and you must honour them in your bot's behaviour. In particular:
  • 400 means you've hit the ratelimit on the REST API
  • 420 means you've hit the ratelimit on the Search or Streaming API
  • 403 means you've hit update (tweeting) limit.

General things you may want to do

Tweet updates from elsewhere

   twitter = TwitterConnection.new() 
   
   at (interval) {
       msg = fetch_external_resource;
       msg.truncate_to_140_chars;
       twitter->update(msg)
   }
       

Check for @-messages and reply

   twitter = TwitterConnection.new() 
   
   mentions = twitter->mentions( since_id => last_mention )
   
   at (interval) {
       foreach mention in mentions {
           mention.parse
           mention.reply
           last_mention = mention.id
       }
   }
   
   
   sub reply(mention) {
       msg = fetch_external_resource()
   
       msg = '@' + mention.sending_user->screen_name + ' ' + msg
       msg.truncate_to_140_chars
       twitter->update(msg, in_reply_to => mention)
   }

Example: inetkami

• Twitter account: @inetkami
• Code: https://github.com/rickscott/inetkami

What it does: fetches, on request:

• METAR (terse weather condition reports intended for aviators)
• Border Wait Times

Other Miscellany

• t, a Ruby command-line interface to the Twitter API