A lightweight Facebook Graph API client
Pull request Compare This branch is 2 commits behind godfat:master.
Failed to load latest commit information.
doc switch homepage Aug 12, 2013
lib use bacon properly (don't pollute top level) Mar 20, 2014
task @ 9a74960 bump task Jan 6, 2014
.gitmodules update gemgem and change the path from godfat-gemgem to gemgem May 5, 2011
.travis.yml just let travis use latest mri if possible Mar 5, 2014
LICENSE a lot of common files added, along with a dummy test (rr+bacon) May 3, 2010
Rakefile we also no longer test against rails2 actually... Nov 15, 2013
rest-graph.gemspec bump gemspec Jan 6, 2014


rest-graph Build Status

by Cardinal Blue http://cardinalblue.com

Tutorial on setting up a sample Facebook application with Rails 3 and RestGraph could be found on samplergthree. Instead, if you're an experienced Ruby programmer, you might also want to look at detailed documents.



A lightweight Facebook Graph API client

We have moved the development from rest-graph to rest-more. From now on, we would only fix bugs in rest-graph rather than adding features, and we would only backport important changes from rest-more once in a period. If you want the latest goodies, please see rest-more Otherwise, you can stay with rest-graph with bugs fixes.


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


  • Tested with MRI 1.8.7 and 1.9.2 and Rubinius 1.2.2. Because of development gems can't work well on JRuby, let me know if rest-graph is working on JRuby, thanks!

  • (must) pick one HTTP client:

    • gem install rest-client
    • gem install em-http-request
  • (optional) pick one JSON parser/generator:

    • gem install yajl-ruby
    • gem install json
    • gem install json_pure
  • (optional) parse access_token in HTTP_COOKIE

    • gem install rack
  • (optional) to use rest-graph/test_util

    • gem install rr


gem install rest-graph

Or if you want development version, put this in Gemfile:

gem 'rest-graph', :git => 'git://github.com/godfat/rest-graph.git',
                  :submodules => true

Or as a Rails2 plugin:

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


require 'rest-graph'
rg = RestGraph.new(:access_token => 'myaccesstokenfromfb')
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 < ActionController::Base
  include RestGraph::RailsUtil
  before_filter :setup

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

  def setup
    rest_graph_setup(:app_id               => '123',
                     :canvas               => 'mycanvas',
                     :auto_authorize_scope => 'email')
                     # See below for more options

Default setup

New RestGraph objects can read their default setup configuration from a YAML configuration file. Which is the same as passing to rest_graph_setup.

To enable, just require anywhere:

require 'rest-graph'

Or if you're using bundler, add this line into Gemfile:

gem 'rest-graph'


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 default
       :old_server    => 'https://api.facebook.com/'  , # this is default
       :accept        => 'text/javascript'            , # this is default
       :lang          => 'en-us'                      , # 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{ |error, url| raise ::RestGraph::Error.parse(error, url) }
       # 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_method    => method(:puts),
       # This way, any log message would be output by puts. If you want to
       # change the log format, use log_handler instead. See below:

       :log_handler   => lambda{ |event|
           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.

                 # == All the above RestGraph options, plus
                 :canvas                 => 'mycanvas', # default ''
                 :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          => true      , # 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
                 # standalone site or iframe canvas application, you might
                 # want to just use the Rails (or other framework) session

Alternate ways to setup RestGraph:

  1. Set upon RestGraph object creation:

    rg = RestGraph.new :app_id => 1234
  2. Set via the rest_graph_setup call in a Controller:

    rest_graph_setup :app_id => 1234
  3. Load from a YAML file

    require 'rest-graph/config_util'
    RestGraph.load_config('path/to/rest-graph.yaml', 'production')
    rg = RestGraph.new
  4. Load config automatically

    require 'rest-graph'  # under Rails, would load config/rest-graph.yaml
    rg = RestGraph.new
  5. Override directly

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


Facebook Graph API:


# GET https://graph.facebook.com/me?access_token=TOKEN

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

# extra options:
#   auto_decode: Bool # decode with json or not in this API request
#                     # default: auto_decode in rest-graph instance
#       timeout: Int  # the timeout for this API request
#                     # default: timeout in rest-graph instance
#        secret: Bool # use secret_acccess_token or not
#                     # default: false
#         cache: Bool # use cache or not; if it's false, update cache, too
#                     # default: true
#    expires_in: Int  # control when would the cache be expired
#                     # default: nil
#         async: Bool # use eventmachine for http client or not
#                     # default: false, but true in aget family
#       headers: Hash # additional hash you want to pass
#                     # default: {}
rg.get('me', {:metadata => '1'}, :secret => true, expires_in => 600)

# When using eventmachine
rg.get('me', {:metadata => '1'}, :async => true) do |result|
  # This block is called even on failure


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


Make an arbitrary FQL query

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


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


Call functionality from Facebook's old REST API:

  { :message    => 'Greetings',
    :attachment => {:name => 'Wikipedia',
                    :href => 'http://wikipedia.org/',
                    :caption => 'Wikipedia says hi.',
                    :media => [{:type => 'image',
                                :src  => 'http://wikipedia.org/logo.png',
                                :href => 'http://wikipedia.org/'}]
    :action_links => [{:text => 'Go to Wikipedia',
                       :href => 'http://wikipedia.org/'}
  :auto_decode => false) # You'll need to set auto_decode to false for
                         # this API request if Facebook is not returning
                         # a proper formatted JSON response. Otherwise,
                         # this could be omitted.

# Some Old Rest API requires a special access token with app secret
# inside of it. For those methods, use secret_old_rest instead of the
# usual old_rest with common access token.
rg.secret_old_rest('admin.getAppProperties', :properties => 'app_id')

Utility Methods:


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:


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




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


Default values

Read from the rest-graph.yaml file.


Other ways of getting an access token


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')


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')


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])


  • Andrew Liu (@eggegg)
  • andy (@coopsite)
  • Barnabas Debreczeni (@keo)
  • Bruce Chu (@bruchu)
  • Ethan Czahor (@ethanz5)
  • Florent Vaucelle (@florent)
  • Jaime Cham (@jcham)
  • John Fan (@johnfan)
  • Lin Jen-Shin (@godfat)
  • Mariusz Pruszynski (@snicky)
  • Nicolas FouchĂ© (@nfo)
  • topac (@topac)
  • Yutaro Sugai (@hokkai7go)


Apache License 2.0

Copyright (c) 2010-2014, 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


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.