rorra-twitter_oauth

h1. Twitter OAuth REST API client library for Ruby

h2. Install the gem

sudo gem install twitter_oauth # (via gemcutter)

h2. Using the gem

To make authorized requests with the client library you'll need to "create a Twitter OAuth Application":http://twitter.com/oauth_clients/new.

See "sinitter":http://github.com/moomerman/sinitter/tree/master for a full website integration example.

h2. Unauthorized request example

The Twitter API can be called to make public requests without needing any client credentials. Most methods will not work in this mode but some of them do. An example to retrieve the public details about a Twitter user is below.

client = TwitterOAuth::Client.new  

puts client.show('twitter')
=> => {"status"=>{"truncated"=>false, "favorited"=>false, "text"=>"Update on service issues http://tinyurl.com/ca872j", "id"=>1357776683, "in_reply_to_user_id"=>nil, "in_reply_to_status_id"=>nil, "source"=>"twitterfeed", "created_at"=>"Fri Mar 20 01:17:35 +0000 2009"}, "name"=>"Twitter", "profile_sidebar_fill_color"=>"CDFFFF", "profile_sidebar_border_color"=>"8a6447", "profile_background_tile"=>false, "profile_link_color"=>"0000ff", "url"=>"http://twitter.com", "favourites_count"=>0, "id"=>783214, "description"=>"Always wondering what everyone's doing.", "profile_text_color"=>"000000", "protected"=>false, "utc_offset"=>-28800, "screen_name"=>"twitter", "profile_background_color"=>"9ae4e8", "time_zone"=>"Pacific Time (US & Canada)", "followers_count"=>469150, "profile_background_image_url"=>"http://static.twitter.com/images/themes/theme1/bg.gif", "friends_count"=>30, "statuses_count"=>290, "location"=>"San Francisco, CA", "profile_image_url"=>"http://s3.amazonaws.com/twitter_production/profile_images/75075164/twitter_bird_profile_normal.png", "created_at"=>"Tue Feb 20 14:35:54 +0000 2007"}

You can also access to the search API which is available in either authorized or unauthorized modes.

search = client.search('twitter')
search.results.size => 20
search.results.first.from_user => "josephpred"
search.results.first.text
=> "Useful public service Twitter account for those of you hitting Tahoe or just needing to cross the pass to Reno: @i80chains"

h2. Authorized request example

To use the full power of the Twitter API you need to authorize your application and a valid Twitter user via OAuth. An example showing how to update the status of an authorized user is below.

Firstly we need to create an instance of the client with your application client credentials you have been given by Twitter when you set up your application.

client = TwitterOAuth::Client.new(
    :consumer_key => 'YOUR_APP_CONSUMER_KEY',
    :consumer_secret => 'YOURA_APP_CONSUMER_SECRET'
)
request_token = client.request_token(:oauth_callback => oauth_confirm_url)
#:oauth_callback required for web apps, since oauth gem by default force PIN-based flow 
#( see http://groups.google.com/group/twitter-development-talk/browse_thread/thread/472500cfe9e7cdb9/848f834227d3e64d )


request_token.authorize_url
=> http://twitter.com/oauth/authorize?oauth_token=TOKEN

In your application your user would be redirected to Twitter to authorize the application at this point. You'll need to store the request token (usually in the session) for later. The code continues below assuming the user has authorized your application.

access_token = client.authorize(
  request_token.token,
  request_token.secret,
  :oauth_verifier => params[:oauth_verifier]
)

client.authorized?
=> true

client.update('checking out the twitter_oauth library') # sends a twitter status update

Now if you keep hold of the access_token (usually in the database) for this user you won't need to re-authorize them next time. When you create an instance of the client you can just pass in the access token and secret that you have stored.

access_token = @user.access_token # assuming @user
client = TwitterOAuth::Client.new(
    :consumer_key => 'YOUR_CONSUMER_KEY',
    :consumer_secret => 'YOUR-CONSUMER-SECRET',
    :token => access_token.token, 
    :secret => access_token.secret
)

client.authorized?
=> true

h2. Working with a Proxy

Services such as "Apigee Analytics and API Management":http://apigee.com/ require you to proxy your API requests through their servers. The workflow is as follows.

First you need to authorize the Twitter user via OAuth directly via the Twitter API (this part cannot be proxied)

client = TwitterOAuth::Client.new(
    :consumer_key => 'YOUR_APP_CONSUMER_KEY',
    :consumer_secret => 'YOURA_APP_CONSUMER_SECRET'
)
request_token = client.request_token(:oauth_callback => 'YOUR_CALLBACK_URL')

request_token.authorize_url
=> http://twitter.com/oauth/authorize?oauth_token=TOKEN

The user is sent to Twitter to allow the application to access their account and then you need to obtain the access token for the user

access_token = client.authorize(
  request_token.token,
  request_token.secret,
  :oauth_verifier => params[:oauth_verifier]
)

client.authorized?
=> true

Now you can make all further API calls through the proxy of your choice:

access_token = @user.access_token # assuming @user
client = TwitterOAuth::Client.new(
    :proxy => 'http://XXX.YYY.apigee.com',
    :consumer_key => 'YOUR_CONSUMER_KEY',
    :consumer_secret => 'YOUR-CONSUMER-SECRET',
    :token => access_token.token, 
    :secret => access_token.secret
)

client.authorized?
=> true

client.update('Proxy via Apigee is working')