RAILS-TWITTER-OAUTH-SAMPLE

Prepared by: paul gallagher - tardate.com Repository: github.com/tardate/rails-twitter-oauth-sample/tree/master Demonstration site: rails-twitter-oauth-sample.heroku.com Related blog post: tardate.blogspot.com/2009/06/using-twitter-oauth-with-rails-sample.html

Purpose

Demonstrates the use of rails with the Twitter RESTful API with OAuth 1.0a. Uses the oauth ruby gem.

Other References

1. Twitter API documentation - apiwiki.twitter.com/
2. OAuth gem github.com/pelle/oauth/tree/master
3. Twitter OAuth gem (another REST API client library for Ruby - not used in this example) github.com/moomerman/twitter_oauth/tree/master

Required gems

These need to be installed in addition to all standard gems required by rails:

json (1.1.6 at time of writing) oauth (0.3.5 at time of writing)

NB: for heroku deployment, these are specified in the .gems file in the root of the project

STEP-BY-STEP (how the app was created)

1. Install oauth gem

        gem install oauth

2. create the application shell

        rails rails-twitter-oauth-sample
        cd rails-twitter-oauth-sample
        rake db:create

3. create a member scaffold

        ruby script/generate scaffold member twitter_id:integer screen_name:string token:string secret:string profile_image_url:string

Member model updated to use screen_name as the key:

                def to_param
                        screen_name
                end

4. Prepare the database

        rake db:migrate

5. Create the oauth support in ./lib

twitter_oauth.rb

• Implements TwitterOauth class, which is a wrapper around the oauth gem, providing specific support for twitter.
• As a design principle, the TwitterOauth class logs and re-raises any errors that occur; some custom error classes are defined to suit.
• It includes implementations for many of the twitter api methods (but not all at this point)

oauth_system.rb

• A controller mixin module to provide twitter oauth support in an application.
• Uses the TwitterOauth class for oauth functionality.
• Works specifically with the Member ActiveRecord class to update/verify user details.
• It includes wrappers for many of the twitter api methods, basically to reroute errors into the flash hash.

6. Modify MembersController to use OAuth

        # include the oauth_system mixin
        include OauthSystem
        # specify oauth to be on all user-specific actions
        before_filter :oauth_login_required, :except => [ :callback, :signout, :index ]

7. Specify routes

Map members resources Hook /members/callback method to module OauthSystem.callback

        map.resources :members,
          :collection => { :callback => :get }

Hook /signout method to module OauthSystem.signout:

        map.signout '/signout', :controller => 'members', :action => 'signout'

For the sample app, use MembersController.index as the landing page:

        map.root      :controller => "members"

8. Customise views and controller methods for some basic functionality

MembersController actions

• index - a basic landing page
• show - main page for logged-in user
• partialfriends - xhr responder to render friends list
• partialfollowers - xhr responder to render followers list
• partialmentions - xhr responder to render mentions list
• partialdms - xhr responder to render direct messages list

9. Add rake task to demonstrate proxy-login

See lib/tasks/test.rake: demo_proxy_login task connects as the last member and exercises the API a bit

To execute:

        rake demo_proxy_login

10. Configuring twitter application keys

Register your application at twitter.com/oauth_clients

Be sure to select the following settings in the registration:

• Application Type = Browser
• Callback URL = the fully qualified callback to your app e.g. rails-twitter-oauth-sample.heroku.com/members/callback
• Default Access type = Read & Write (if you want to be able to do things like post status updates)
• Use Twitter for login = yes

Note the "application key" and "consumer secret" numbers that twitter generates - these are unique for your application and are required to complete the configuration.

Add the twitter application key and consumer secret as operating system environment variables (TWOAUTH_KEY and TWOAUTH_SECRET respectively).

Set your callback URL as operating system environment variable (TWOAUTH_CALLBACK).

Alternatively, you can edit config/environment.rb to set these directly.

If you are using heroku, add the environment keys using the heroky utility (gem):

        heroku config:add TWOAUTH_KEY=8N029N81 TWOAUTH_SECRET=9s83109d3+583493190 TWOAUTH_CALLBACK=http://rails-twitter-oauth-sample.heroku.com/members/callback

11. Testing the application locally

When you register the application at twitter, you will specify a fully qualified callback URL e.g. rails-twitter-oauth-sample.heroku.com/members/callback

This is the address that twitter sends users back to after the twitter authentication step.

To test on a local development machine (not known on the web/in DNS as the domain name in the callback), you can simply add the registered domain to your hosts file (aliasing localhost) e.g.

        127.0.0.1       rails-twitter-oauth-sample.heroku.com

NB: most browsers will need to be restarted each time you change this, as the resolved name will have been cached if you have already used the address.