The OAuth plugin was created by Pelle Braendgaard to easily implement OAuth Consumers in Rails applications. In this page we will focus on creating an OAuth consumer application for Picwing using the OAuth plugin.

Installation

You first need to install the oauth gem which is the core OAuth ruby library:

   sudo gem install oauth

Next, you need to install the oauth-plugin gem:

   sudo gem install oauth-plugin

You should add the following in the gem dependency section of environment.rb:

   config.gem "oauth"

   config.gem "oauth-plugin"

Generating your new controllers

The oauth_consumer generator creates a controller to manage the authentication flow between your application and any number of external OAuth secured applications that you wish to connect to, like Picwing.

To run the generator, simply run:

   ./script/generate oauth_consumer

This generates the OauthConsumerController as well as the ConsumerToken model.

Configuration

Next, you'll need to tell your application about your Picwing OAuth credentials. You get your Picwing OAuth credentials by signing up for our API. You put your credentials in:

   config/initializers/oauth_consumers.rb

Add your OAuth credentials to the OAUTH_CREDENTIALS global variable, replace "key" and "secret" with the values provided to you by Picwing:

   OAUTH_CREDENTIALS = {
     :picwing => {
       :key => "key",
       :secret => "secret",
       :options => {
         :site => "http://www.picwing.com"
       }
     }
   }

Running your migrations

The database changes are defined in:

   db/migrate/XXX_create_oauth_consumer_tokens.rb
		

Run them as any other normal migration in rails with:

   rake db:migrate

Making a RESTful request to the Picwing API

Now, you are almost ready to make RESTful requests to the Picwing API. Add a has_one association in your user model:

   has_one :picwing, :class_name => "PicwingToken", :dependent => :destroy

This will enable you to do :

   response = current_user.picwing.client.get('/api/user/albums.xml')
   picwing_albums_xml = response.body

The response body will look something like this:

<?xml version="1.0" encoding="UTF-8" ?>

<user login="johndoe@mailinator.com" 

      email_address="johndoe@mailinator.com" 

      full_name="John Doe"> 

  <album id="123"

         album_title="Photos of Baby" 

         album_description="Photos of My Baby" 

         album_thumbnail="http://www.picwing.com/123/thumb.jpg"

         submission_email_address="Baby"

         printing_plan="11"

         printing_plan_name="4 Recipients+"

         shipments_per_month="2"

         recipients_allowed="4"

         prints_allowed="15"

         used_prints="12"

         ship_date="Nov 28">

  </album>

  <album id="124" 

         album_title="The Doe Family" 

         album_description="The Doe Family" 

         album_thumbnail="http://www.picwing.com/124/thumb.jpg"

         submission_email_address="DoeFamily"

         printing_plan="0"

         printing_plan_name="No Prints"

         shipments_per_month="0"

         recipients_allowed="0"

         prints_allowed="0"

         used_prints="0"

         ship_date="none">

  </album>

  <album id="125" 

         album_title="Personal Album" 

         album_description="Personal Album" 

         album_thumbnail="http://www.picwing.com/125/thumb.jpg"

         submission_email_address="DoePersonal"

         printing_plan="10"

         printing_plan_name="Pay As You Go+"

         shipments_per_month="2"

         recipients_allowed="unlimited"

         prints_allowed="unlimited"

         used_prints="12"

         ship_date="Nov 28">

  </album>

</user>

You can then parse the xml to display the picwing albums of the current user.

Authorizing your application

But wait. Before you can make any authenticated API calls on a users's behalf, the user first needs to give permission for you to do so. In order to ask permission from the users, redirect them to:

   /oauth_consumers/[SERVICE_NAME]

Where SERVICE_NAME is the name you set in the OAUTH_CREDENTIALS hash. If you've been following the examples above, it would be:

   /oauth_consumers/picwing

This will redirect the user to the service authorization screen. When the user accepts they'll be redirected to a callback url. For now, the callback url is:

   /oauth_consumers/[SERVICE_NAME]/callback

Again, SERVICE_NAME is the name you set in the OAUTH_CREDENTIALS hash. If you've been following the examples above, it would be:

   /oauth_consumers/picwing/callback

Now you'll be able to make API calls on on the user's behalf.

Have any questions?

Don't hesitate to send us an email to: support@picwing.com