rest-graph 1.4.6

DESCRIPTION:

A super simple Facebook Open Graph API client

FEATURES:

Simple Graph API call
Simple FQL call
Utility to extract access_token and check sig in cookies

REQUIREMENTS:

Tested with MRI 1.8.7 and 1.9.2 and Rubinius HEAD
gem install rest-client
gem install json (optional)
gem install json_pure (optional)
gem install rack (optional, to parse access_token in HTTP_COOKIE)

INSTALL:

gem install rest-graph

or if you want rails plugin and bleeding edge

script/plugin install git://github.com/cardinalblue/rest-graph.git

QUICK START:

require 'rest-graph'
rg = RestGraph.new(:access_token => 'myaccesstokenfromfb')
rg.get('me')
rg.get('me/likes')
rg.get('search', :q => 'taiwan')

Obtaining an access token

If you are using Rails, we recommend that you include a module called RestGraph::RailsUtil into your Controllers. (Your code contributions for other Ruby frameworks would be appreciated!). RestGraph::RailsUtil adds the following two methods to your Controllers:

rest_graph_setup:   Attempts to find an access_token from the environment
                    and initializes a RestGraph object with it.
                    Most commonly used inside a filter.

rest_graph:         Accesses the RestGraph object by rest_graph_setup.

Example usage:

class MyController
  include RestGraph::RailsUtil
  before_filter do
    rest_graph_setup(:app_id               => '123',
                     :canvas               => 'mycanvas',
                     :auto_authorize_scope => 'email')
                     # See below for more options
  end

  def myaction
    @medata = rest_graph.get('me')
  end
end

Default setup

New RestGraph objects can read their default setup configuration from a YAML configuration file.

Sample

To enable, just require anywhere:

require 'rest-graph/auto_load'

If you are using Rails and rest-graph as a gem, you can include this when you specify the gem in your environment file by using:

config.gem 'rest-graph', :lib => 'rest-graph/auto_load'

Or if using bundler, by adding this line into your Gemfile:

gem 'rest-graph', :require => 'rest-graph/auto_load'

Setup options:

Here are ALL the available options for new instance of RestGraph.

rg = RestGraph.new(
       :access_token  => TOKEN                        , # default nil
       :graph_server  => 'https://graph.facebook.com/', # this is the default
       :old_server    => 'https://api.facebook.com/'  , # this is the default
       :accept        => 'text/javascript'            , # this is the default
       :lang          => 'en-us'                      , # this affect search
       :auto_decode   =>  true                        , # decode by json
                                                        # default true
       :app_id        => '123'                        , # default nil
       :secret        => '1829'                       , # default nil

       :cache         => {}                           ,
       # A cache for the same API call. Any object quacks like a hash should
       # work, and Rails.cache works, too. (because of a patch in RailsUtil)

       :error_handler => lambda{ |hash| raise ::RestGraph::Error.new(hash) },
       # This handler callback is only called if auto_decode is
       # set to true, otherwise, it's ignored. And raising exception
       # is the default unless you're using RailsUtil and enabled
       # auto_authorize. That way, RailsUtil would do redirect instead
       # of raising an exception.

       :log_handler   => lambda{ |event|
         Rails.logger.
           debug("Spent #{event.duration} requesting #{event.url}")})
       # You might not want to touch this if you're using RailsUtil.
       # Otherwise, the default behavior is do nothing. (i.e. no logging)

And here are ALL the available options for rest_graph_setup. Note that all options for RestGraph instance are also valid options for rest_graph_setup.

rest_graph_setup(#
                 # == All the above RestGraph options, plus
                 #
                 :canvas                 => 'mycanvas', # default ''
                 :iframe                 => true      , # default false
                 :auto_authorize         => true      , # default false
                 :auto_authorize_scope   => 'email'   , # default ''
                 :auto_authorize_options => {}        , # default {}
                 # auto_authorize means it will do redirect to oauth
                 # API automatically if the access_token is invalid or
                 # missing. So you would like to setup scope if you're
                 # using it. Note that: setting scope implies setting
                 # auto_authorize to true, even it's false.

                 :ensure_authorized      => false     , # default false
                 # This means if the access_token is not there,
                 # then do auto_authorize.

                 :write_session          => false     , # default false
                 :write_cookies          => false     , # default false
                 :write_handler          =>
                   lambda{ |fbs| @cache[uid] = fbs }  , # default nil
                 :check_handler          =>
                   lambda{       @cache[uid] })         # default nil
                 # If we're not using Facebook JavaScript SDK,
                 # then we'll need to find a way to store the fbs,
                 # which contains access_token and/or user id.
                 # In a FBML canvas application, it seems session
                 # doesn't work right, so you'll need cookies or
                 # your custom handler to store it. In a standalone
                 # site or iframe canvas application, you might want
                 # to just use the Rails (or other framework) session.

Setup procedures:

Set upon RestGraph object creation:
```
rg = RestGraph.new :app_id => 1234
```
Set via the rest_graph_setup call in a Controller:
```
rest_graph_setup :app_id => 1234
```

Load from a YAML file

require 'rest-graph/load_config'
RestGraph::LoadConfig.load_config!('path/to/rest-graph.yaml', 'production')
rg = RestGraph.new

Load config automatically

require 'rest-graph/auto_load'  # under Rails, load config/rest-graph.yaml
rg = RestGraph.new

Override directly

module MyDefaults
  def default_app_id
    '456'
  end

  def default_secret
    'category theory'
  end
end
RestGraph.send(:extend, MyDefaults)
rg = RestGraph.new

API REFERENCE:

Facebook Graph API:

get

# GET https://graph.facebook.com/me?access_token=TOKEN
rg.get('me')

# GET https://graph.facebook.com/me?metadata=1&access_token=TOKEN
rg.get('me', :metadata => '1')

post

rg.post('me/feed', :message => 'bread!')

fql

Make an arbitrary FQL query

rg.fql('SELECT name FROM page WHERE page_id="123"')

fql_multi

rg.fql_multi(:q1 => 'SELECT name FROM page WHERE page_id="123"',
             :q2 => 'SELECT name FROM page WHERE page_id="456"')

old_rest

Call functionality from Facebook’s old REST API:

rg.old_rest(
  'stream.publish',
  { :message    => 'Greetings',
    :attachment => {:name => 'Wikipedia',
                    :href => 'http://wikipedia.org/',
                    :caption => 'Wikipedia says hi.',
                    :media => [{:type => 'image',
                                :src  => 'http://wikipedia.org/favicon.ico',
                                :href => 'http://wikipedia.org/'}]
                   }.to_json,
    :action_links => [{:text => 'Go to Wikipedia',
                       :href => 'http://wikipedia.org/'}
                     ].to_json
  },
  :suppress_decode => true) # You'll need to set suppress_decode to true
                            # if Facebook is not returning a proper JSON
                            # response. Otherwise, this could be omitted.

Utility Methods:

parse_xxxx

All the methods that obtain an access_token will automatically save it.

If you have the session in the cookies, then RestGraph can parse the cookies:

rg.parse_cookies!(cookies)

If you’re writing a Rack application, you might want to parse the session directly from Rack env:

rg.parse_rack_env!(env)

access_token

rg.access_token

Data associated with the access_token (which might or might not available, depending on how the access_token was obtained).

rg.data
rg.data['uid']
rg.data['expires']

Default values

Read from the rest-graph.yaml file.

RestGraph.default_xxxx

Other ways of getting an access token

authorize_url

Returns the redirect URL for authorizing

# https://graph.facebook.com/oauth/authorize?
#   client_id=123&redirect_uri=http%3A%2F%2Fw3.org%2F
rg.authorize_url(:redirect_uri => 'http://w3.org/', :scope => 'email')

authorize!

Makes a call to Facebook to convert the authorization “code” into an access token:

# https://graph.facebook.com/oauth/access_token?
#   code=CODE&client_id=123&client_secret=1829&
#   redirect_uri=http%3A%2F%2Fw3.org%2F
rg.authorize!(:redirect_uri => 'http://w3.org/', :code => 'CODE')

exchange_sessions

Takes a session key from the old REST API (non-Graph API) and converts to an access token:

# https://graph.facebook.com/oauth/exchange_sessions?sessions=SESSION
rg.exchange_sessions(:sessions => params[:fb_sig_session_key])

LICENSE:

Apache License 2.0

Copyright (c) 2010, Cardinal Blue

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.