= RGData

RGData makes it easy to get data from Google's Data APIs. It streamlines the parts that give you headaches (requests, OAUTH2 authentication, etc.) and gives you back good ole Ruby objects.

An Example:

domain = 'redningja.com' profiles = RGData::API::Profiles.retrieve domain, oauth_token: 'access_token_thatlookslikegibberish' #=> [#<RGData::Model::Profile full_name: 'Jared Ning'>, ...]

profiles.first.full_name

profiles.map(&:emails)

== Installation

gem install rgdata

RGData.config do client_id client_secret end

== Authentication

To retrieve data, you need an oauth token (a.k.a. access token). There's a lot of setup, but after that it should be easy.

• Setup
  • Get your client_id and client_secret
    • https://code.google.com/apis/console
    • Click on 'API Access' at the left.
    • Look for OAuth2 Credentials and you'll find your client_id and client_secret
  • While you're here, you may want to list your redirect URIs if you know what they will be. These must match your authentication requests (more on this in just a bit).
• Request authentication. (Depending on which API you are using, there may be specific instructions you may want to tell your user about. See the individual APIs classes for specifics.)
  • Your user will go to the request URL generated for you by calling, for example, RGData::API::Profiles.request_url(redirect_uri) # redirect_uri MUST BE LISTED IN YOUR API CONSOLE.
  • They will be promted by Google to authenticate and grant permission.
• Successful authentication will return an authorization code in the form of a callback to redirect_uri. The authorization code is attached to the URL as a parameter - e.g. http://redirect_back.com?authorization_code=42istheanswer.
• Now you have the dough, so go get the bread. (You get 1 shot at this. Once the authorization_code is used on Google, it's useless.) Use this authorization code to swap for a hash with all the goodies. The hash has 3 parts:
  • access_token: This is what we're after. You can use this immediately to retrieve data. You can also get one by using refresh_token which we'll get to in a sec.
  • expires_in: You have this many seconds to use access_token before it expires.
  • refresh_token: See below.
• Finalyy, once you have your access token, you can start accessing the data.

=== Refresh tokens

A refresh token won't get you into the data, but it will allow you to get more access tokens in the future. Keep this if you don't want your users to re-authenticate over and over again. REFRESH TOKENS EXPIRE AFTER 24 HOURS. To get another access token:

RGData::API::Profiles.swap_refresh_token(refresh_token)

For convenience, APIs are smart enough to do this work for you:

RGData::API::Profiles.retrieve domain, refresh_token: refresh_token

=== Client-side and native application authentication

TODO

== Retrieving data

Easy:

RGData::API::Profiles.retrieve domain, oauth_token: oauth_token

RGData::API::Profiles.retrieve domain, refresh_token: refresh_token

_.first.full_name #=> 'Jared Ning'

=== Query parameters, Retrieving a single profile, etc.

TODO

There are more ways to retrieve information (e.g. http://code.google.com/googleapps/domain/profiles/developers_guide_protocol.html#Retrieving). Currently the gem only supports retrieving all (or at least all that Google allows in one request).

== Supported APIs

• Profiles

=== Add more

Please feel free to contribute more APIs. Take a look at lib/rgdata/apis/profiles.rb and lib/rgdata/models/profile.rb to see how easy it is. For the API, just find the scope (link below)

== TODOs

Feel free to contribute.

• Client-side authentication
• Native application authentication
• Retrieving data with query parameters (limit, start index, etc.)
• Retrieving individual (as opposed to all)
• Lots of more APIs.
• Capture error messages: If google denies something, there may be some useful error messages.

== Testing

This gem tests live with Google. You'll need to set some environment variables for your own client_id, client_secret, refresh_token, and domain. See mspec/spec_helper.rb. I set them in my .bash_profile.

export GOOGLE_APPS_CLIENT_ID='1234567890.apps.googleusercontent.com' export GOOGLE_APPS_CLIENT_SECRET='blahblahblah' export GOOGLE_APPS_REFRESH_TOKEN='sierra_mist_foobar' export GOOGLE_APPS_DOMAIN='redningja.com'

== Compatibility

Ruby 1.9. Want 1.8 support? Go fork yourself. gem-testers: http://test.rubygems.org/gems/rgdata

== Useful links

• OAuth2 for server side: http://code.google.com/apis/accounts/docs/OAuth2.html#SS
• Scopes: http://code.google.com/apis/gdata/faq.html#AuthScopes
• Each API class should have a link to its corresponding Google API page.