[ANN] rest-graph 1.3.0 - A super simple Facebook Open Graph API client

Discussion in 'Ruby' started by Lin Jen-Shin, Jun 11, 2010.

  1. Lin Jen-Shin

    Lin Jen-Shin Guest

    = rest-graph 1.3.0
    by Cardinal Blue ( http://cardinalblue.com )

    == LINKS:

    * http://github.com/cardinalblue/rest-graph
    * http://rubygems.org/gems/rest-graph
    * http://rdoc.info/projects/cardinalblue/rest-graph
    * http://groups.google.com/group/rest-graph/topics

    == 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

    == CHANGES in 1.3.0

    * Now rest-graph is rescuing all exceptions from rest-client.
    * Added RestGraph#exchange_sessions to exchange old sessions to access
    tokens.

    * Added RestGraph#old_rest, see:
    http://developers.facebook.com/docs/reference/rest/

    * Now all API request accept an additional options argument,
    you may pass :suppress_decode => true to turn off auto-decode this
    time.
    e.g. rg.get('bad/json', {:query => 'string'}, :suppress_decode =>
    true)
    This is for Facebook who didn't always return JSON in response.

    * Renamed fql_server to old_server.
    * Favor yaji/json_gem first, then falls back to json, and json_pure.
    * Fixed a bug that cookie format from Facebook varies. No idea why.

    for RailsUtil:

    * Big and fat refactoring in RailsUtil, see example for detail:
    http://github.com/cardinalblue/rest-graph/tree/rest-graph-1.3.0/example
    * url_for and link_to would auto pass :host option if it's inside
    canvas.

    == SYNOPSIS:

    # If you feel SYNOPSIS is so hard to understand, please read
    # {examples}[http://github.com/cardinalblue/rest-graph/tree/master/
    example].

    require 'rest-graph'

    # Every option is optional.
    rg = RestGraph.new:)access_token => 'tok',
    :graph_server => 'https://graph.facebook.com/',
    :eek:ld_server => 'https://api.facebook.com/',
    :accept => 'text/javascript',
    :lang => 'en-us', # this affect search
    :auto_decode => true , # decode by json
    :app_id => '123' ,
    :secret => '1829' ,

    # This handler callback is only called if auto_decode is set to
    true,
    # otherwise, it's ignored.
    :error_handler =>
    lambda{ |hash|
    raise ::RestGraph::Error.new(hash) },

    # You might want to do this in Rails to do debug logging:
    :log_handler =>
    lambda{ |duration, url|
    Rails.logger.debug("RestGraph " \
    "spent #{duration} " \
    "requesting #{url}")
    })

    # You might want to do redirect instead of raising an exception,
    # that is automatically redirect the user to authorization page
    # if the access token is unavailable. This way, you don't have to
    # check if the token is expired or not. If the token is expired,
    # it will automatically do authorization again. For that purpose,
    # you might want to include RestGraph::RailsUtil in your Rails'
    # controller. For example:
    class UserController < ApplicationController
    include RestGraph::RailsUtil
    before_filter :rest_graph_setup
    end
    # Please read:
    # {examples}[http://github.com/cardinalblue/rest-graph/tree/master/
    example].
    # for more detail, and other frameworks utils wanted!

    # Other simple API call:
    rg.get('me') # GET https://graph.facebook.com/me?access_token=tok
    rg.get('4/likes') # GET https://graph.facebook.com/4/likes?access_token=tok

    # GET https://graph.facebook.com/search?q=taiwan&access_token=tok
    rg.get('search', :q => 'taiwan')

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

    # POST https://graph.facebook.com/me/feed?message=bread!&access_token=tok
    rg.post('me/feed', :message => 'bread!')

    # For fully blown cookies hash
    rg = RestGraph.new:)app_id => '123', :secret => '1829')
    rg.parse_cookies!(cookies) # auto save access_token if sig checked
    rg.data['uid'] # => facebook uid

    # FQL query, same as:
    # GET https://api.facebook.com/method/fql.query?query=
    # SELECT+name+FROM+page+WHERE+page_id%3D%22123%22&
    # format=json&access_token=...
    rg.fql('SELECT name FROM page WHERE page_id="123"')

    # FQL multiquery, same as:
    # GET https://api.facebook.com/method/fql.multiquery?query=
    # %7BSELECT+name+FROM+page+WHERE+page_id%3D%22123%22&%2C
    # SELECT+name+FROM+page+WHERE+page_id%3D%22456%22&%7D
    # format=json&access_token=...
    rg.fql_multi:)q1 => 'SELECT name FROM page WHERE page_id="123"',
    :q2 => 'SELECT name FROM page WHERE page_id="456"')

    # Setup default settings:
    module MyDefaults
    def default_app_id
    '456'
    end

    def default_secret
    'category theory'
    end
    end
    RestGraph.send:)extend, MyDefaults)

    # Automatically load config:
    require 'rest-graph/auto_load' # under Rails, load config/rest-
    graph.yaml
    RestGraph.new # all default options would honor
    config
    RestGraph.new:)app_id => '123') # default could be override as well

    # Manually load config:
    require 'rest-graph/load_config'
    RestGraph::LoadConfig.load_config!('path/to/rest-graph.yaml', 'env')

    # See test/config/rest-graph.yaml for an example for config.

    # OAuth utilites:
    # https://graph.facebook.com/oauth/authorize?client_id=123&
    RestGraph.new.authorize_url:)redirect_uri => 'http://w3.org/')

    # Get access token by:
    # https://graph.facebook.com/oauth/access_token?code=edoc&
    rg = RestGraph.new
    rg.authorize!:)redirect_uri => 'http://w3.org/', :code => 'edoc')
    rg.access_token # your access_token is now available
    rg.data['expires'] # other values as well

    # Exchange old session key for access token:
    # https://graph.facebook.com/oauth/exchange_sessions?sessions=sess
    rg.exchange_sessions:)sessions => params[:fb_sig_session_key])

    # Call 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)

    == REQUIREMENTS:

    * Tested with MRI 1.8.7 and 1.9.1
    * 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


    == 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.
     
    Lin Jen-Shin, Jun 11, 2010
    #1
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Guest

    super.super.super how?

    Guest, Feb 19, 2005, in forum: Java
    Replies:
    24
    Views:
    10,863
    Darryl Pierce
    Feb 24, 2005
  2. Dutt
    Replies:
    1
    Views:
    711
    Peter Bromberg [C# MVP]
    Feb 8, 2008
  3. Lin Jen-Shin
    Replies:
    0
    Views:
    285
    Lin Jen-Shin
    May 6, 2010
  4. Lin Jen-Shin
    Replies:
    0
    Views:
    304
    Lin Jen-Shin
    May 21, 2010
  5. Replies:
    2
    Views:
    163
Loading...

Share This Page