rest-graph 1.7.0 → 1.8.0

data/README.md

@@ -0,0 +1,367 @@
+# rest-graph
+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][].
+
+[samplergthree]: https://github.com/cardinalblue/samplergthree
+[detailed documents]: https://github.com/cardinalblue/rest-graph/blob/master/doc/ToC.md
+
+## LINKS:
+
+* [github](http://github.com/cardinalblue/rest-graph)
+* [rubygems](http://rubygems.org/gems/rest-graph)
+* [rdoc](http://rdoc.info/projects/cardinalblue/rest-graph)
+* [mailing list](http://groups.google.com/group/rest-graph/topics)
+
+## DESCRIPTION:
+
+A lightweight Facebook Graph API client
+
+## FEATURES:
+
+* Simple Graph API call
+* Simple FQL call
+* Utility to extract access_token and check sig in cookies/signed_request
+
+## REQUIREMENTS:
+
+* 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
+
+## INSTALLATION:
+
+    gem install rest-graph
+
+Or if you want development version, put this in Gemfile:
+
+    gem 'rest-graph', :git => 'git://github.com/cardinalblue/rest-graph.git
+
+Or as a Rails2 plugin:
+
+    ./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 < ActionController::Base
+      include RestGraph::RailsUtil
+      before_filter :setup
+
+      def myaction
+        @medata = rest_graph.get('me')
+      end
+
+      private
+      def setup
+        rest_graph_setup(:app_id               => '123',
+                         :canvas               => 'mycanvas',
+                         :auto_authorize_scope => 'email')
+                         # See below for more options
+      end
+    end
+
+### 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.
+
+* [Example](test/config/rest-graph.yaml)
+
+To enable, just require anywhere:
+
+    require 'rest-graph'
+
+Or if you're using bundler, add this line into Gemfile:
+
+    gem 'rest-graph'
+
+## 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 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{|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_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|
+             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 ''
+                     :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
+        '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')
+
+    # extra options:
+    #   auto_decode: Bool # decode with json or not in this method call
+    #                     # default: auto_decode 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: nothing
+    #         async: Bool # use eventmachine for http client or not
+    #                     # default: false, but true in aget family
+    rg.get('me', {:metadata => '1'}, :secret => true, expires_in => 600)
+
+#### post
+
+    rg.post('me/feed', :message => 'bread!')
+
+#### fql
+
+Make an arbitrary [FQL][] query
+
+[FQL]: http://developers.facebook.com/docs/reference/fql/
+
+    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/logo.png',
+                                    :href => 'http://wikipedia.org/'}]
+                       }.to_json,
+        :action_links => [{:text => 'Go to Wikipedia',
+                           :href => 'http://wikipedia.org/'}
+                         ].to_json
+      },
+      :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:
+
+#### parse_???
+
+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_???
+
+### 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.

data/Rakefile

@@ -1,57 +1,42 @@
 # encoding: utf-8
 
-begin
-  require 'bones'
-rescue LoadError
-  abort '### Please install the "bones" gem ###'
-end
-
-ensure_in_path 'lib'
-proj = 'rest-graph'
-require "#{proj}/version"
-
-Bones{
-  ruby_opts [''] # silence warning for now
-
-  version RestGraph::VERSION
-
-  depend_on 'rest-client'    , :development => true
-  depend_on 'em-http-request', :development => true
+require "#{dir = File.dirname(__FILE__)}/task/gemgem"
+Gemgem.dir = dir
 
-  depend_on 'rack'     , :development => true
+($LOAD_PATH << File.expand_path("#{Gemgem.dir}/lib" )).uniq!
 
-  depend_on 'yajl-ruby', :development => true
-  depend_on 'json'     , :development => true
-  depend_on 'json_pure', :development => true
+desc 'Generate gemspec'
+task 'gem:spec' do
+  Gemgem.spec = Gemgem.create do |s|
+    require 'rest-graph/version'
+    s.name        = 'rest-graph'
+    s.version     = RestGraph::VERSION
+    # s.executables = [s.name]
 
-  depend_on 'ruby-hmac', :development => true
+    %w[].each{ |g| s.add_runtime_dependency(g) }
+    %w[rest-client em-http-request rack yajl-ruby json json_pure ruby-hmac
+       webmock bacon rr].each{ |g| s.add_development_dependency(g) }
 
-  depend_on 'rr'       , :development => true
-  depend_on 'webmock'  , :development => true
-  depend_on 'bacon'    , :development => true
+    s.authors     = ['Cardinal Blue', 'Lin Jen-Shin (godfat)']
+    s.email       = ['dev (XD) cardinalblue.com']
+  end
 
-  name    proj
-  url     "http://github.com/cardinalblue/#{proj}"
-  authors ['Cardinal Blue', 'Lin Jen-Shin (aka godfat 真常)']
-  email   'dev (XD) cardinalblue.com'
-
-  history_file   'CHANGES'
-   readme_file   'README.rdoc'
-   ignore_file   '.gitignore'
-  rdoc.include   ['\w+']
-  rdoc.exclude   ['test', 'doc', 'Rakefile', 'example']
-}
-
-CLEAN.include Dir['**/*.rbc']
-
-task :default do
-  Rake.application.options.show_task_pattern = /./
-  Rake.application.display_tasks_and_comments
+  Gemgem.write
 end
 
 desc 'Run example tests'
 task 'test:example' => ['gem:install'] do
-  sh "cd example/rails2; #{Gem.ruby} -S rake test"
+  %w[rails3 rails2].each{ |framework|
+    opts = Rake.application.options
+    args = (opts.singleton_methods - [:rakelib, 'rakelib']).map{ |arg|
+             if arg.to_s !~ /=$/ && opts.send(arg)
+               "--#{arg}"
+             else
+               ''
+             end
+           }.join(' ')
+    sh "cd example/#{framework}; #{Gem.ruby} -S rake test #{args}"
+  }
 end
 
 desc 'Run all tests'