README.rdoc in rest-graph-1.4.5 vs README.rdoc in rest-graph-1.4.6
- old
+ new
@@ -1,6 +1,6 @@
-= rest-graph 1.4.5
+= rest-graph 1.4.6
by Cardinal Blue ( http://cardinalblue.com )
== LINKS:
* {github}[http://github.com/cardinalblue/rest-graph]
@@ -8,174 +8,221 @@
* {rdoc}[http://rdoc.info/projects/cardinalblue/rest-graph]
* {mailing list}[http://groups.google.com/group/rest-graph/topics]
== DESCRIPTION:
- A super simple Facebook Open Graph API client
+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
-== QUICK START:
+== REQUIREMENTS:
- # In typical use, here's how you use RestGraph. Note that the syntax follows
- # closely to the Graph API URL syntax, making it easy to use. First, suppose
- # that you already have an access_token, represented by TOKEN:
+* 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)
- require 'rest-graph'
- rg = RestGraph.new(:access_token => TOKEN)
+== INSTALL:
- # GET https://graph.facebook.com/me?access_token=TOKEN
- rg.get('me')
+ gem install rest-graph
- # GET https://graph.facebook.com/me/likes?access_token=TOKEN
- rg.get('me/likes')
+or if you want rails plugin and bleeding edge
- # GET https://graph.facebook.com/search?q=taiwan&access_token=TOKEN
+ 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
- # Next, we explain how to use RestGraph to obtain the 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:
- # If you are using Rails, we recommend that you include a module
- # called RailsUtil into your controllers, which will configure RestGraph.
- # (Your code contributions for other Ruby frameworks would be appreciated!)
- # There is an option in RailsUtil called "auto_authorize" which will cause
- # RestGraph to automatically redirect the user to the authorization page if
- # the access token is unavailable or has expired. (This way, you don't have
- # to check if the token is expired or not.)
+ 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.
- # Here is an example:
+ rest_graph: Accesses the RestGraph object by rest_graph_setup.
- class UserController < ApplicationController
- include RestGraph::RailsUtil
- before_filter :filter_rest_graph_setup
+=== Example usage:
- def index
- # rest_graph_setup provides rest_graph as a RestGraph instance
- @profile = rest_graph.get('me')
+ 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
- # your code
-
- private
- def filter_rest_graph_setup
- # Please see RestGraph::RailsUtil#rest_graph_options for all options.
- rest_graph_setup(:auto_authorize_scope => 'publish_stream,email',
- :app_id => '123',
- :canvas => RestGraph.default_canvas)
+ def myaction
+ @medata = rest_graph.get('me')
end
end
+=== Default setup
- # You might wonder how do we setup app_id, secret, and other stuffs?
- # You could pass them in rest_graph_setup(:app_id => 1234), or setup
- # in a config YAML file. Here's a config example:
-{rest-graph.yaml}[http://github.com/cardinalblue/rest-graph/blob/master/test/config/rest-graph.yaml]
- # For a QUICK START, we recommend that put this config file under
- # config/rest-graph.yaml and require 'rest-graph/auto_load' to automatically
- # load the config to setup default values for RestGraph in your application.
- # in Rails 2.x, you might want to add this line into config/environment.rb:
+New RestGraph objects can read their default setup configuration from a
+YAML configuration file.
+* {Sample}[http://github.com/cardinalblue/rest-graph/blob/master/test/config/rest-graph.yaml]
+
+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'
- # While for bundler, you might want to add this line into Gemfile:
+Or if using bundler, by adding this line into your Gemfile:
gem 'rest-graph', :require => 'rest-graph/auto_load'
-== SYNOPSIS:
+=== Setup options:
- # Here are ALL the available options for new instance of RestGraph.
- # All options are optional:
+Here are ALL the available options for new instance of RestGraph.
- rg = RestGraph.new(:access_token => TOKEN,
- :graph_server => 'https://graph.facebook.com/',
- :old_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' ,
- :cache => {} , # a cache for the same API call
+ 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
- # 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) },
+ :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)
- # 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}")
- })
+ :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)
- # API calls:
+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.
- # GET https://graph.facebook.com/me?access_token=TOKEN
- rg.get('me')
+ 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.
- # GET https://graph.facebook.com/me?metadata=1&access_token=TOKEN
- rg.get('me', :metadata => '1')
+ :ensure_authorized => false , # default false
+ # This means if the access_token is not there,
+ # then do auto_authorize.
- # POST https://graph.facebook.com/me/feed?message=bread%21&access_token=tok
- rg.post('me/feed', :message => 'bread!')
+ :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.
-== UTILITY FUNCTIONS:
+=== Setup procedures:
- # If you have the session in the cookies,
- # then RestGraph can parse the cookies:
- rg.parse_cookies!(cookies) # auto save access_token if sig is correct
- rg.data['uid'] # => facebook uid
+1. Set upon RestGraph object creation:
- # If you're writing a Rack application, you might want to parse
- # the session directly from Rack env:
- rg.parse_rack_env!(env) # auto save access_token if sig is correct
- rg.data['uid'] # => facebook uid
+ rg = RestGraph.new :app_id => 1234
- # The following method yields 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')
+2. Set via the rest_graph_setup call in a Controller:
- # The following method 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&redirect_uri=http%3A%2F%2Fw3.org%2F&
- # client_secret=1829
- rg.authorize!(:redirect_uri => 'http://w3.org/', :code => 'CODE')
- rg.access_token # your access_token is now available
- rg.data['expires'] # other values are available in data
+ rest_graph_setup :app_id => 1234
- # The following method 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
- params[:fb_sig_session_key] # => SESSION
- rg.exchange_sessions(:sessions => params[:fb_sig_session_key])
+3. Load from a YAML file
- # The following method allows for an arbitrary FQL query to made
- # GET https://api.facebook.com/method/fql.query?query=
- # SELECT+name+FROM+page+WHERE+page_id%3D%22123%22&
- # format=json&access_token=tok
+ require 'rest-graph/load_config'
+ RestGraph::LoadConfig.load_config!('path/to/rest-graph.yaml', 'production')
+ rg = RestGraph.new
+
+4. Load config automatically
+
+ require 'rest-graph/auto_load' # under Rails, load config/rest-graph.yaml
+ rg = RestGraph.new
+
+5. 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}[http://developers.facebook.com/docs/reference/fql/] query
+
rg.fql('SELECT name FROM page WHERE page_id="123"')
- # The following method allows for multiple FQL query to made
- # http://developers.facebook.com/docs/reference/rest/fql.multiquery
- # 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=tok
+==== fql_multi
rg.fql_multi(:q1 => 'SELECT name FROM page WHERE page_id="123"',
:q2 => 'SELECT name FROM page WHERE page_id="456"')
- # The following method makes it possible to call functionality
- # from Facebook's old REST API:
+==== old_rest
+Call functionality from Facebook's old REST API:
+
rg.old_rest(
'stream.publish',
{ :message => 'Greetings',
:attachment => {:name => 'Wikipedia',
:href => 'http://wikipedia.org/',
@@ -190,50 +237,69 @@
},
: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.
- # Here are 3 possible ways to set up the default settings:
+=== Utility Methods:
- # (1) set it directly
- module MyDefaults
- def default_app_id
- '456'
- end
+==== parse_xxxx
- def default_secret
- 'category theory'
- end
- end
- RestGraph.send(:extend, MyDefaults)
+All the methods that obtain an access_token will automatically save it.
- # or (2) Load defaults from a YAML config file:
- require 'rest-graph/load_config'
- RestGraph::LoadConfig.load_config!('path/to/rest-graph.yaml', 'development')
+If you have the session in the cookies,
+then RestGraph can parse the cookies:
- RestGraph.new # app_id would be 456
- RestGraph.new(:app_id => '123') # defaults could be overridden
+ rg.parse_cookies!(cookies)
- # or (3) Load config automatically
- require 'rest-graph/auto_load' # under Rails, load config/rest-graph.yaml
+If you're writing a Rack application, you might want to parse
+the session directly from Rack env:
- # Please read: for an example of config file.
- # Note that :auto_authorize_scope and friends is only for RailsUtil.
-{rest-graph.yaml}[http://github.com/cardinalblue/rest-graph/blob/master/test/config/rest-graph.yaml]
+ rg.parse_rack_env!(env)
-== REQUIREMENTS:
+==== access_token
-* Tested with MRI 1.8.7 and 1.9.1 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)
+ rg.access_token
-== INSTALL:
+Data associated with the access_token (which might or might not
+available, depending on how the access_token was obtained).
- > gem install rest-graph
- # or if you want rails plugin and bleeding edge
- > script/plugin install git://github.com/cardinalblue/rest-graph.git
+ 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