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

From Code4Lib
Jump to: navigation, search
(+more OAuth and setup details)
(+much more detail)
Line 40: Line 40:
 
== Creating a new app ==
 
== Creating a new app ==
  
=== First steps ===
+
=== 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
 
* https://dev.twitter.com/apps/new
* sign in with your twitter account
+
* sign in with your twitter (bot's) account
 
* fill out basic info about your app  
 
* fill out basic info about your app  
 
* agree to be a good citizen, as detailed below
 
* agree to be a good citizen, as detailed below
Line 73: Line 78:
  
  
=== Setup ===
+
=== Set up the App ===
  
* after you've set up your app, you receive your OAuth consumer keys:
+
* after you've set up your app, you receive your OAuth consumer keys for the app:
 
** '''<tt>consumer_key</tt>'''
 
** '''<tt>consumer_key</tt>'''
 
** '''<tt>consumer_secret</tt>'''
 
** '''<tt>consumer_secret</tt>'''
Line 90: Line 95:
 
You can also fill in the rest of the self-explanatory fields in the Details and Settings tabs as you like (organization, etc).
 
You can also fill in the rest of the self-explanatory fields in the Details and Settings tabs as you like (organization, etc).
  
== Bot-specific stuff ==
 
  
* create an account for your bot
+
=== Authorize the App on your Bot's Account ===
* authorize it on your app
+
  
 +
While still logged in under the bot's account, navigate to the app's page and generate your access token:
  
== Rules of Conduct ==
+
Details tab → Your Access Token ''*click*''
  
  
=== General Rules of the Road and TOS ===
+
 
 +
== Rules of the Road ==
 +
 
 +
 
 +
=== General Rules of Conduc and TOS ===
  
 
* https://dev.twitter.com/terms/api-terms
 
* https://dev.twitter.com/terms/api-terms
Line 106: Line 114:
 
=== Rate limits ===
 
=== Rate limits ===
  
*  
+
* 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
 +
 
 +
Things that '''do not''' count against your limit
 +
* checking the rate limit (it can change, though nowadays it rarely does)
 +
 
 +
 
  
 
=== Other gotchas ===
 
=== Other gotchas ===
  
 
* Repeated tweets
 
* Repeated tweets
 +
* failed reqs
 +
 +
 +
== General things you may want to do ==
 +
 +
=== Check for @-messages and reply ===
 +
 +
=== Tweet updates from elsewhere ===
 +
  
  

Revision as of 15:14, 24 May 2012

Presenter: Rick Scott - @shadowspar

API Overview


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


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

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*


Rules of the Road

General Rules of Conduc and TOS

Rate limits

  • 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

Things that do not count against your limit

  • checking the rate limit (it can change, though nowadays it rarely does)


Other gotchas

  • Repeated tweets
  • failed reqs


General things you may want to do

Check for @-messages and reply

Tweet updates from elsewhere

Example

http://twitter.com/inetkami https://github.com/rickscott/inetkami

Other Miscellany

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