Twitter OAuth REST API client library for Ruby
Install the gem
sudo gem install twitter_oauth # (via gemcutter)
Using the gem
To make authorized requests with the client library you’ll need to create a Twitter OAuth Application.
See sinitter for a full website integration example.
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"=>"<a href=\"http://twitterfeed.com\">twitterfeed</a>", "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"
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 => 'YOUR_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.
NOTE: Above we called the client.request_token(...) method, this authorizes the application on every call. You can also use the client.authentication_request_token(...) method which automatically redirects back to your application if the user has previously authorized the app.
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_APP_CONSUMER_SECRET',
:token => access_token.token,
:secret => access_token.secret
)
client.authorized?
=> true
PIN-based flow
If you’re writing a command line application or desktop app, you will probably want to use the PIN-based authorization method rather than the website redirect method.
client = TwitterOAuth::Client.new(
:consumer_key => 'YOUR_CONSUMER_KEY',
:consumer_secret => 'YOUR_APP_CONSUMER_SECRET'
)
request_token = client.authentication_request_token(
:oauth_callback => 'oob'
)
puts request_token.authorize_url
print 'Please visit the URL and enter the code: '
code = gets.strip
access_token = client.authorize(
request_token.token,
request_token.secret,
:oauth_verifier => code
)
client.authorized?
=> true
The special oauth callback value of oob tells Twitter you want to do the PIN-based authentication. The user goes to the authorization URL to get their unique code and they paste that into your application. Finally we authorize the user with this code.
Working with a Proxy
Services such as Apigee Analytics and API Management 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')