koala 1.0.0 → 1.2.0

data/lib/koala/graph_batch_api.rb

@@ -0,0 +1,97 @@
+module Koala
+  module Facebook
+      module GraphBatchAPIMethods
+
+      def self.included(base)
+        base.class_eval do
+          attr_reader :original_api
+          
+          def initialize(access_token, api)
+            super(access_token)
+            @original_api = api
+          end
+
+          alias_method :graph_call_outside_batch, :graph_call
+          alias_method :graph_call, :graph_call_in_batch
+
+          alias_method :check_graph_api_response, :check_response
+          alias_method :check_response, :check_graph_batch_api_response
+        end
+      end
+
+      def batch_calls
+        @batch_calls ||= []
+      end
+
+      def graph_call_in_batch(path, args = {}, verb = "get", options = {}, &post_processing)
+          # for batch APIs, we queue up the call details (incl. post-processing)
+          batch_calls << BatchOperation.new(
+            :url => path,
+            :args => args,
+            :method => verb,
+            :access_token => options['access_token'] || access_token,
+            :http_options => options,
+            :post_processing => post_processing
+          )
+          nil # batch operations return nothing immediately
+      end
+
+      def check_graph_batch_api_response(response)
+        if response.is_a?(Hash) && response["error"] && !response["error"].is_a?(Hash)
+          APIError.new("type" => "Error #{response["error"]}", "message" => response["error_description"])
+        else
+          check_graph_api_response(response)
+        end
+      end
+
+      def execute(http_options = {})
+        return [] unless batch_calls.length > 0
+        # Turn the call args collected into what facebook expects
+        args = {}
+        args["batch"] = MultiJson.encode(batch_calls.map { |batch_op|
+          args.merge!(batch_op.files) if batch_op.files
+          batch_op.to_batch_params(access_token)
+        })
+
+        batch_result = graph_call_outside_batch('/', args, 'post', http_options) do |response|
+          # map the results with post-processing included
+          index = 0 # keep compat with ruby 1.8 - no with_index for map
+          response.map do |call_result|
+            # Get the options hash
+            batch_op = batch_calls[index]
+            index += 1
+
+            if call_result
+              # (see note in regular api method about JSON parsing)
+              body = MultiJson.decode("[#{call_result['body'].to_s}]")[0]
+
+              unless call_result["code"].to_i >= 500 || error = check_response(body)
+                # Get the HTTP component they want
+                data = case batch_op.http_options[:http_component]
+                when :status
+                  call_result["code"].to_i
+                when :headers
+                  # facebook returns the headers as an array of k/v pairs, but we want a regular hash
+                  call_result['headers'].inject({}) { |headers, h| headers[h['name']] = h['value']; headers}
+                else
+                  body
+                end
+
+                # process it if we are given a block to process with
+                batch_op.post_processing ? batch_op.post_processing.call(data) : data
+              else
+                error || APIError.new({"type" => "HTTP #{call_result["code"].to_s}", "message" => "Response body: #{body}"})
+              end
+            else
+              nil
+            end
+          end
+        end
+        
+        # turn any results that are pageable into GraphCollections
+        batch_result.inject([]) {|processed_results, raw| processed_results << GraphCollection.evaluate(raw, @original_api)}
+      end
+
+    end
+  end
+end

data/lib/koala/graph_collection.rb

@@ -0,0 +1,59 @@
+module Koala
+  module Facebook
+    class GraphCollection < Array
+      # This class is a light wrapper for collections returned
+      # from the Graph API.
+      #
+      # It extends Array to allow direct access to the data colleciton
+      # which should allow it to drop in seamlessly.
+      #
+      # It also allows access to paging information and the
+      # ability to get the next/previous page in the collection
+      # by calling next_page or previous_page.
+      attr_reader :paging, :api, :raw_response
+
+      def self.evaluate(response, api)
+        # turn the response into a GraphCollection if it's pageable; if not, return the original response
+        response.is_a?(Hash) && response["data"].is_a?(Array) ? self.new(response, api) : response
+      end
+    
+      def initialize(response, api)
+        super response["data"]
+        @paging = response["paging"]
+        @raw_response = response
+        @api = api
+      end
+
+      # defines methods for NEXT and PREVIOUS pages
+      %w{next previous}.each do |this|
+
+        # def next_page
+        # def previous_page
+        define_method "#{this.to_sym}_page" do
+          base, args = send("#{this}_page_params")
+          base ? @api.get_page([base, args]) : nil
+        end
+
+        # def next_page_params
+        # def previous_page_params
+        define_method "#{this.to_sym}_page_params" do
+          return nil unless @paging and @paging[this]
+          parse_page_url(@paging[this])
+        end
+      end
+
+      def parse_page_url(url)
+        match = url.match(/.com\/(.*)\?(.*)/)
+        base = match[1]
+        args = match[2]
+        params = CGI.parse(args)
+        new_params = {}
+        params.each_pair do |key,value|
+          new_params[key] = value.join ","
+        end
+        [base,new_params]
+      end
+
+    end
+  end
+end

data/lib/koala/http_service.rb

@@ -0,0 +1,176 @@
+require 'faraday'
+
+module Koala
+  class Response
+    attr_reader :status, :body, :headers
+    def initialize(status, body, headers)
+      @status = status
+      @body = body
+      @headers = headers
+    end
+  end
+
+  module HTTPService
+    # common functionality for all HTTP services
+
+    class << self
+      attr_accessor :faraday_middleware, :http_options
+    end
+
+    @http_options ||= {}
+    
+    DEFAULT_MIDDLEWARE = Proc.new do |builder|
+      builder.request :multipart
+      builder.request :url_encoded
+      builder.adapter Faraday.default_adapter
+    end
+
+    def self.server(options = {})
+      server = "#{options[:rest_api] ? Facebook::REST_SERVER : Facebook::GRAPH_SERVER}"
+      server.gsub!(/\.facebook/, "-video.facebook") if options[:video]
+      "#{options[:use_ssl] ? "https" : "http"}://#{options[:beta] ? "beta." : ""}#{server}"
+    end
+
+    def self.make_request(path, args, verb, options = {})
+      # if the verb isn't get or post, send it as a post argument
+      args.merge!({:method => verb}) && verb = "post" if verb != "get" && verb != "post"
+
+      # turn all the keys to strings (Faraday has issues with symbols under 1.8.7) and resolve UploadableIOs
+      params = args.inject({}) {|hash, kv| hash[kv.first.to_s] = kv.last.is_a?(UploadableIO) ? kv.last.to_upload_io : kv.last; hash}
+
+      # figure out our options for this request   
+      request_options = {:params => (verb == "get" ? params : {})}.merge(http_options || {}).merge(process_options(options))
+      request_options[:use_ssl] = true if args["access_token"] # require http if there's a token
+
+      # set up our Faraday connection
+      # we have to manually assign params to the URL or the
+      conn = Faraday.new(server(request_options), request_options, &(faraday_middleware || DEFAULT_MIDDLEWARE))
+
+      response = conn.send(verb, path, (verb == "post" ? params : {}))
+      Koala::Response.new(response.status.to_i, response.body, response.headers)
+    end
+
+    def self.encode_params(param_hash)
+      # unfortunately, we can't use to_query because that's Rails, not Ruby
+      # if no hash (e.g. no auth token) return empty string
+      # this is used mainly by the Batch API nowadays
+      ((param_hash || {}).collect do |key_and_value|
+        key_and_value[1] = MultiJson.encode(key_and_value[1]) unless key_and_value[1].is_a? String
+        "#{key_and_value[0].to_s}=#{CGI.escape key_and_value[1]}"
+      end).join("&")
+    end
+    
+    # deprecations
+    # not elegant or compact code, but temporary
+    
+    def self.always_use_ssl
+      Koala::Utils.deprecate("HTTPService.always_use_ssl is now HTTPService.http_options[:use_ssl]; always_use_ssl will be removed in a future version.")
+      http_options[:use_ssl]
+    end
+
+    def self.always_use_ssl=(value)
+      Koala::Utils.deprecate("HTTPService.always_use_ssl is now HTTPService.http_options[:use_ssl]; always_use_ssl will be removed in a future version.")
+      http_options[:use_ssl] = value
+    end
+    
+    def self.timeout
+      Koala::Utils.deprecate("HTTPService.timeout is now HTTPService.http_options[:timeout]; .timeout will be removed in a future version.")
+      http_options[:timeout]
+    end
+
+    def self.timeout=(value)
+      Koala::Utils.deprecate("HTTPService.timeout is now HTTPService.http_options[:timeout]; .timeout will be removed in a future version.")
+      http_options[:timeout] = value
+    end
+    
+    def self.timeout
+      Koala::Utils.deprecate("HTTPService.timeout is now HTTPService.http_options[:timeout]; .timeout will be removed in a future version.")
+      http_options[:timeout]
+    end
+
+    def self.timeout=(value)
+      Koala::Utils.deprecate("HTTPService.timeout is now HTTPService.http_options[:timeout]; .timeout will be removed in a future version.")
+      http_options[:timeout] = value
+    end
+    
+    def self.proxy
+      Koala::Utils.deprecate("HTTPService.proxy is now HTTPService.http_options[:proxy]; .proxy will be removed in a future version.")
+      http_options[:proxy]
+    end
+
+    def self.proxy=(value)
+      Koala::Utils.deprecate("HTTPService.proxy is now HTTPService.http_options[:proxy]; .proxy will be removed in a future version.")
+      http_options[:proxy] = value
+    end
+    
+    def self.ca_path
+      Koala::Utils.deprecate("HTTPService.ca_path is now (HTTPService.http_options[:ssl] ||= {})[:ca_path]; .ca_path will be removed in a future version.")
+      (http_options[:ssl] || {})[:ca_path]
+    end
+
+    def self.ca_path=(value)
+      Koala::Utils.deprecate("HTTPService.ca_path is now (HTTPService.http_options[:ssl] ||= {})[:ca_path]; .ca_path will be removed in a future version.")
+      (http_options[:ssl] ||= {})[:ca_path] = value
+    end
+    
+    def self.ca_file
+      Koala::Utils.deprecate("HTTPService.ca_file is now (HTTPService.http_options[:ssl] ||= {})[:ca_file]; .ca_file will be removed in a future version.")
+      (http_options[:ssl] || {})[:ca_file]
+    end
+
+    def self.ca_file=(value)
+      Koala::Utils.deprecate("HTTPService.ca_file is now (HTTPService.http_options[:ssl] ||= {})[:ca_file]; .ca_file will be removed in a future version.")
+      (http_options[:ssl] ||= {})[:ca_file] = value
+    end
+
+    def self.verify_mode
+      Koala::Utils.deprecate("HTTPService.verify_mode is now (HTTPService.http_options[:ssl] ||= {})[:verify_mode]; .verify_mode will be removed in a future version.")
+      (http_options[:ssl] || {})[:verify_mode]
+    end
+
+    def self.verify_mode=(value)
+      Koala::Utils.deprecate("HTTPService.verify_mode is now (HTTPService.http_options[:ssl] ||= {})[:verify_mode]; .verify_mode will be removed in a future version.")
+      (http_options[:ssl] ||= {})[:verify_mode] = value
+    end
+
+    def self.process_options(options)
+      if typhoeus_options = options.delete(:typhoeus_options)
+        Koala::Utils.deprecate("typhoeus_options should now be included directly in the http_options hash.  Support for this key will be removed in a future version.")
+        options = options.merge(typhoeus_options)
+      end
+      
+      if ca_file = options.delete(:ca_file)
+        Koala::Utils.deprecate("http_options[:ca_file] should now be passed inside (http_options[:ssl] = {}) -- that is, http_options[:ssl][:ca_file].  Support for this key will be removed in a future version.")
+        (options[:ssl] ||= {})[:ca_file] = ca_file
+      end
+
+      if ca_path = options.delete(:ca_path)
+        Koala::Utils.deprecate("http_options[:ca_path] should now be passed inside (http_options[:ssl] = {}) -- that is, http_options[:ssl][:ca_path].  Support for this key will be removed in a future version.")
+        (options[:ssl] ||= {})[:ca_path] = ca_path
+      end
+
+      if verify_mode = options.delete(:verify_mode)
+        Koala::Utils.deprecate("http_options[:verify_mode] should now be passed inside (http_options[:ssl] = {}) -- that is, http_options[:ssl][:verify_mode].  Support for this key will be removed in a future version.")
+        (options[:ssl] ||= {})[:verify_mode] = verify_mode
+      end
+      
+      options
+    end   
+  end
+  
+  module TyphoeusService
+    def self.deprecated_interface
+      # support old-style interface with a warning
+      Koala::Utils.deprecate("the TyphoeusService module is deprecated; to use Typhoeus, set Faraday.default_adapter = :typhoeus.  Enabling Typhoeus for all Faraday connections.")
+      Faraday.default_adapter = :typhoeus
+    end
+  end
+
+  module NetHTTPService
+    def self.deprecated_interface
+      # support old-style interface with a warning
+      Koala::Utils.deprecate("the NetHTTPService module is deprecated; to use Net::HTTP, set Faraday.default_adapter = :net_http.  Enabling Net::HTTP for all Faraday connections.")
+      Faraday.default_adapter = :net_http
+    end
+  end
+end

data/lib/koala/oauth.rb

@@ -0,0 +1,191 @@
+module Koala
+  module Facebook
+    class OAuth
+      attr_reader :app_id, :app_secret, :oauth_callback_url
+      def initialize(app_id, app_secret, oauth_callback_url = nil)
+        @app_id = app_id
+        @app_secret = app_secret
+        @oauth_callback_url = oauth_callback_url
+      end
+
+      def get_user_info_from_cookie(cookie_hash)
+        # Parses the cookie set Facebook's JavaScript SDK.
+        # You can pass Rack/Rails/Sinatra's cookie hash directly to this method.
+        #
+        # If the user is logged in via Facebook, we return a dictionary with the
+        # keys "uid" and "access_token". The former is the user's Facebook ID,
+        # and the latter can be used to make authenticated requests to the Graph API.
+        # If the user is not logged in, we return None.
+
+        if signed_cookie = cookie_hash["fbsr_#{@app_id}"]
+          parse_signed_cookie(signed_cookie)
+        elsif unsigned_cookie = cookie_hash["fbs_#{@app_id}"]
+          parse_unsigned_cookie(unsigned_cookie)
+        end
+      end
+      alias_method :get_user_info_from_cookies, :get_user_info_from_cookie
+
+      def get_user_from_cookie(cookies)
+        if info = get_user_info_from_cookies(cookies)
+          string = info["uid"]
+        end
+      end
+      alias_method :get_user_from_cookies, :get_user_from_cookie
+
+      # URLs
+
+      def url_for_oauth_code(options = {})
+        # for permissions, see http://developers.facebook.com/docs/authentication/permissions
+        permissions = options[:permissions]
+        scope = permissions ? "&scope=#{permissions.is_a?(Array) ? permissions.join(",") : permissions}" : ""
+        display = options.has_key?(:display) ? "&display=#{options[:display]}" : ""
+
+        callback = options[:callback] || @oauth_callback_url
+        raise ArgumentError, "url_for_oauth_code must get a callback either from the OAuth object or in the options!" unless callback
+
+        # Creates the URL for oauth authorization for a given callback and optional set of permissions
+        "https://#{GRAPH_SERVER}/oauth/authorize?client_id=#{@app_id}&redirect_uri=#{callback}#{scope}#{display}"
+      end
+
+      def url_for_access_token(code, options = {})
+        # Creates the URL for the token corresponding to a given code generated by Facebook
+        callback = options[:callback] || @oauth_callback_url
+        raise ArgumentError, "url_for_access_token must get a callback either from the OAuth object or in the parameters!" unless callback
+        "https://#{GRAPH_SERVER}/oauth/access_token?client_id=#{@app_id}&redirect_uri=#{callback}&client_secret=#{@app_secret}&code=#{code}"
+      end
+
+      def get_access_token_info(code, options = {})
+        # convenience method to get a parsed token from Facebook for a given code
+        # should this require an OAuth callback URL?
+        get_token_from_server({:code => code, :redirect_uri => options[:redirect_uri] || @oauth_callback_url}, false, options)
+      end
+
+      def get_access_token(code, options = {})
+        # upstream methods will throw errors if needed
+        if info = get_access_token_info(code, options)
+          string = info["access_token"]
+        end
+      end
+
+      def get_app_access_token_info(options = {})
+        # convenience method to get a the application's sessionless access token
+        get_token_from_server({:type => 'client_cred'}, true, options)
+      end
+
+      def get_app_access_token(options = {})
+        if info = get_app_access_token_info(options)
+          string = info["access_token"]
+        end
+      end
+
+      # Originally provided directly by Facebook, however this has changed
+      # as their concept of crypto changed. For historic purposes, this is their proposal:
+      # https://developers.facebook.com/docs/authentication/canvas/encryption_proposal/
+      # Currently see https://github.com/facebook/php-sdk/blob/master/src/facebook.php#L758
+      # for a more accurate reference implementation strategy.
+      def parse_signed_request(input)
+        encoded_sig, encoded_envelope = input.split('.', 2)
+        signature = base64_url_decode(encoded_sig).unpack("H*").first
+        envelope = MultiJson.decode(base64_url_decode(encoded_envelope))
+
+        raise "SignedRequest: Unsupported algorithm #{envelope['algorithm']}" if envelope['algorithm'] != 'HMAC-SHA256'
+
+        # now see if the signature is valid (digest, key, data)
+        hmac = OpenSSL::HMAC.hexdigest(OpenSSL::Digest::SHA256.new, @app_secret, encoded_envelope)
+        raise 'SignedRequest: Invalid signature' if (signature != hmac)
+
+        return envelope
+      end
+
+      # from session keys
+      def get_token_info_from_session_keys(sessions, options = {})
+        # fetch the OAuth tokens from Facebook
+        response = fetch_token_string({
+          :type => 'client_cred',
+          :sessions => sessions.join(",")
+        }, true, "exchange_sessions", options)
+
+        # Facebook returns an empty body in certain error conditions
+        if response == ""
+          raise APIError.new({
+            "type" => "ArgumentError",
+            "message" => "get_token_from_session_key received an error (empty response body) for sessions #{sessions.inspect}!"
+          })
+        end
+
+        MultiJson.decode(response)
+      end
+
+      def get_tokens_from_session_keys(sessions, options = {})
+        # get the original hash results
+        results = get_token_info_from_session_keys(sessions, options)
+        # now recollect them as just the access tokens
+        results.collect { |r| r ? r["access_token"] : nil }
+      end
+
+      def get_token_from_session_key(session, options = {})
+        # convenience method for a single key
+        # gets the overlaoded strings automatically
+        get_tokens_from_session_keys([session], options)[0]
+      end
+
+      protected
+
+      def get_token_from_server(args, post = false, options = {})
+        # fetch the result from Facebook's servers
+        result = fetch_token_string(args, post, "access_token", options)
+
+        # if we have an error, parse the error JSON and raise an error
+        raise APIError.new((MultiJson.decode(result)["error"] rescue nil) || {}) if result =~ /error/
+
+        # otherwise, parse the access token
+        parse_access_token(result)
+      end
+
+      def parse_access_token(response_text)
+        components = response_text.split("&").inject({}) do |hash, bit|
+          key, value = bit.split("=")
+          hash.merge!(key => value)
+        end
+        components
+      end
+      
+      def parse_unsigned_cookie(fb_cookie)
+        # remove the opening/closing quote
+        fb_cookie = fb_cookie.gsub(/\"/, "")
+
+        # since we no longer get individual cookies, we have to separate out the components ourselves
+        components = {}
+        fb_cookie.split("&").map {|param| param = param.split("="); components[param[0]] = param[1]}
+
+        # generate the signature and make sure it matches what we expect
+        auth_string = components.keys.sort.collect {|a| a == "sig" ? nil : "#{a}=#{components[a]}"}.reject {|a| a.nil?}.join("")
+        sig = Digest::MD5.hexdigest(auth_string + @app_secret)
+        sig == components["sig"] && (components["expires"] == "0" || Time.now.to_i < components["expires"].to_i) ? components : nil
+      end
+      
+      def parse_signed_cookie(fb_cookie)
+        components = parse_signed_request(fb_cookie)
+        if (code = components["code"]) && token_info = get_access_token_info(code, :redirect_uri => '')
+          components.merge(token_info)
+        else
+          nil
+        end
+      end
+
+      def fetch_token_string(args, post = false, endpoint = "access_token", options = {})
+        Koala.make_request("/oauth/#{endpoint}", {
+          :client_id => @app_id,
+          :client_secret => @app_secret
+        }.merge!(args), post ? "post" : "get", {:use_ssl => true}.merge!(options)).body
+      end
+
+      # base 64
+      # directly from https://github.com/facebook/crypto-request-examples/raw/master/sample.rb
+      def base64_url_decode(str)
+        str += '=' * (4 - str.length.modulo(4))
+        Base64.decode64(str.tr('-_', '+/'))
+      end
+    end
+  end
+end

data/lib/koala/realtime_updates.rb

@@ -1,15 +1,13 @@
-require 'koala'
-
 module Koala
   module Facebook
     module RealtimeUpdateMethods
       # note: to subscribe to real-time updates, you must have an application access token
-      
+
       def self.included(base)
         # make the attributes readable
         base.class_eval do
-          attr_reader :app_id, :app_access_token, :secret
-          
+          attr_reader :api, :app_id, :app_access_token, :secret
+
           # parses the challenge params and makes sure the call is legitimate
           # returns the challenge string to be sent back to facebook if true
           # returns false otherwise
@@ -20,7 +18,7 @@ module Koala
                 # you can make sure this is legitimate through two ways
                 # if your store the token across the calls, you can pass in the token value
                 # and we'll make sure it matches
-                (verify_token && params["hub.verify_token"] == verify_token) ||        
+                (verify_token && params["hub.verify_token"] == verify_token) ||
                 # alternately, if you sent a specially-constructed value (such as a hash of various secret values)
                 # you can pass in a block, which we'll call with the verify_token sent by Facebook
                 # if it's legit, return anything that evaluates to true; otherwise, return nil or false
@@ -32,7 +30,7 @@ module Koala
           end
         end
       end
-      
+
       def initialize(options = {})
         @app_id = options[:app_id]
         @app_access_token = options[:app_access_token]
@@ -40,56 +38,52 @@ module Koala
         unless @app_id && (@app_access_token || @secret) # make sure we have what we need
           raise ArgumentError, "Initialize must receive a hash with :app_id and either :app_access_token or :secret! (received #{options.inspect})"
         end
-        
+
         # fetch the access token if we're provided a secret
         if @secret && !@app_access_token
           oauth = Koala::Facebook::OAuth.new(@app_id, @secret)
           @app_access_token = oauth.get_app_access_token
         end
+
+        @graph_api = API.new(@app_access_token)
       end
-      
+
       # subscribes for realtime updates
       # your callback_url must be set up to handle the verification request or the subscription will not be set up
       # http://developers.facebook.com/docs/api/realtime
       def subscribe(object, fields, callback_url, verify_token)
         args = {
-          :object => object, 
+          :object => object,
           :fields => fields,
           :callback_url => callback_url,
           :verify_token => verify_token
         }
         # a subscription is a success if Facebook returns a 200 (after hitting your server for verification)
-        api(subscription_path, args, 'post', :http_component => :status) == 200
+        @graph_api.graph_call(subscription_path, args, 'post', :http_component => :status) == 200
       end
-          
+
       # removes subscription for object
       # if object is nil, it will remove all subscriptions
       def unsubscribe(object = nil)
         args = {}
         args[:object] = object if object
-        api(subscription_path, args, 'delete', :http_component => :status) == 200
+        @graph_api.graph_call(subscription_path, args, 'delete', :http_component => :status) == 200
       end
-  
+
       def list_subscriptions
-        api(subscription_path)["data"]
+        @graph_api.graph_call(subscription_path)
       end
-      
-      def api(*args) # same as GraphAPI
-        response = super(*args) do |response|
-          # check for subscription errors
-          if response.is_a?(Hash) && error_details = response["error"]
-            raise APIError.new(error_details)
-          end
-        end
-      
-        response
-      end    
-      
+
+      def graph_api
+        Koala::Utils.deprecate("the TestUsers.graph_api accessor is deprecated and will be removed in a future version; please use .api instead.")
+        @api
+      end
+
       protected
-      
+
       def subscription_path
         @subscription_path ||= "#{@app_id}/subscriptions"
       end
     end
   end
-end
+end

data/lib/koala/rest_api.rb

@@ -3,21 +3,26 @@ module Koala
     REST_SERVER = "api.facebook.com"
 
     module RestAPIMethods
-      def fql_query(fql)
-        rest_call('fql.query', 'query' => fql)
+      def fql_query(fql, args = {}, options = {})
+        rest_call('fql.query', args.merge(:query => fql), options)
       end
 
-      def rest_call(method, args = {}, options = {})
-        options = options.merge!(:rest_api => true, :read_only => READ_ONLY_METHODS.include?(method))
+      def fql_multiquery(queries = {}, args = {}, options = {})
+        if results = rest_call('fql.multiquery', args.merge(:queries => MultiJson.encode(queries)), options)
+          # simplify the multiquery result format
+          results.inject({}) {|outcome, data| outcome[data["name"]] = data["fql_result_set"]; outcome}
+        end
+      end
 
-        response = api("method/#{method}", args.merge('format' => 'json'), 'get', options) do |response|
+      def rest_call(fb_method, args = {}, options = {}, method = "get")
+        options = options.merge!(:rest_api => true, :read_only => READ_ONLY_METHODS.include?(fb_method.to_s))
+
+        api("method/#{fb_method}", args.merge('format' => 'json'), method, options) do |response|
           # check for REST API-specific errors
           if response.is_a?(Hash) && response["error_code"]
             raise APIError.new("type" => response["error_code"], "message" => response["error_msg"])
           end
         end
-
-        response
       end
 
       # read-only methods for which we can use API-read
@@ -87,4 +92,4 @@ module Koala
     end
 
   end # module Facebook
-end # module Koala
+end # module Koala