koala 1.5.0 → 1.6.0

data/lib/koala/errors.rb

@@ -0,0 +1,86 @@
+module Koala
+
+  class KoalaError < StandardError; end
+
+  module Facebook
+
+    # The OAuth signature is incomplete, invalid, or using an unsupported algorithm
+    class OAuthSignatureError < ::Koala::KoalaError; end
+
+    # Facebook responded with an error to an API request. If the exception contains a nil
+    # http_status, then the error was detected before making a call to Facebook. (e.g. missing access token)
+    class APIError < ::Koala::KoalaError
+      attr_accessor :fb_error_type, :fb_error_code, :fb_error_subcode, :fb_error_message,
+                    :http_status, :response_body
+
+      # Create a new API Error
+      #
+      # @param http_status [Integer] The HTTP status code of the response
+      # @param response_body [String] The response body
+      # @param error_info One of the following:
+      #                   [Hash] The error information extracted from the request 
+      #                          ("type", "code", "error_subcode", "message")
+      #                   [String] The error description
+      #                   If error_info is nil or not provided, the method will attempt to extract
+      #                   the error info from the response_body
+      #
+      # @return the newly created APIError
+      def initialize(http_status, response_body, error_info = nil)
+        if response_body
+          self.response_body = response_body.strip
+        else
+          self.response_body = ''
+        end
+        self.http_status = http_status
+
+        if error_info && error_info.is_a?(String)
+          message = error_info
+        else
+          unless error_info
+            begin
+              error_info = MultiJson.load(response_body)['error'] if response_body
+            rescue
+            end
+            error_info ||= {}
+          end
+
+          self.fb_error_type = error_info["type"]
+          self.fb_error_code = error_info["code"]
+          self.fb_error_subcode = error_info["error_subcode"]
+          self.fb_error_message = error_info["message"]
+
+          error_array = []
+          %w(type code error_subcode message).each do |key|
+            error_array << "#{key}: #{error_info[key]}" if error_info[key]
+          end
+
+          if error_array.empty?
+            message = self.response_body
+          else
+            message = error_array.join(', ')
+          end
+        end
+        message += " [HTTP #{http_status}]" if http_status
+
+        super(message)
+      end
+    end
+
+    # Facebook returned an invalid response body
+    class BadFacebookResponse < APIError; end
+
+    # Facebook responded with an error while attempting to request an access token
+    class OAuthTokenRequestError < APIError; end
+
+    # Any error with a 5xx HTTP status code
+    class ServerError < APIError; end
+
+    # Any error with a 4xx HTTP status code 
+    class ClientError < APIError; end
+
+    # All graph API authentication failures.
+    class AuthenticationError < ClientError; end
+
+  end
+
+end

data/lib/koala/oauth.rb

@@ -139,7 +139,7 @@ module Koala
       # @param code (see #url_for_access_token)
       # @param options any additional parameters to send to Facebook when redeeming the token
       #
-      # @raise Koala::Facebook::APIError if Facebook returns an error response
+      # @raise Koala::Facebook::OAuthTokenRequestError if Facebook returns an error response
       #
       # @return a hash of the access token info returned by Facebook (token, expiration, etc.)
       def get_access_token_info(code, options = {})
@@ -221,21 +221,21 @@ module Koala
       #
       # @param input the signed request from Facebook
       #
-      # @raise RuntimeError if the signature is incomplete, invalid, or using an unsupported algorithm
+      # @raise OAuthSignatureError if the signature is incomplete, invalid, or using an unsupported algorithm
       #
       # @return a hash of the validated request information
       def parse_signed_request(input)
         encoded_sig, encoded_envelope = input.split('.', 2)
-        raise 'SignedRequest: Invalid (incomplete) signature data' unless encoded_sig && encoded_envelope
+        raise OAuthSignatureError, 'Invalid (incomplete) signature data' unless encoded_sig && encoded_envelope
 
         signature = base64_url_decode(encoded_sig).unpack("H*").first
         envelope = MultiJson.load(base64_url_decode(encoded_envelope))
 
-        raise "SignedRequest: Unsupported algorithm #{envelope['algorithm']}" if envelope['algorithm'] != 'HMAC-SHA256'
+        raise OAuthSignatureError, "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)
+        raise OAuthSignatureError, 'Invalid signature' if (signature != hmac)
 
         envelope
       end
@@ -254,10 +254,7 @@ module Koala
 
         # 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}!"
-          })
+          raise BadFacebookResponse.new(200, '', "get_token_from_session_key received an error (empty response body) for sessions #{sessions.inspect}!")
         end
 
         MultiJson.load(response)
@@ -282,13 +279,8 @@ module Koala
 
       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.load(result)["error"] rescue nil) || {}) if result =~ /error/
-
-        # otherwise, parse the access token
-        parse_access_token(result)
+        response = fetch_token_string(args, post, "access_token", options)
+        parse_access_token(response)
       end
 
       def parse_access_token(response_text)
@@ -318,9 +310,12 @@ module Koala
         if code = components["code"]
           begin
             token_info = get_access_token_info(code, :redirect_uri => '')
-          rescue Koala::Facebook::APIError => err
-            return nil if err.message =~ /Code was invalid or expired/
-            raise
+          rescue Koala::Facebook::OAuthTokenRequestError => err
+            if err.fb_error_type == 'OAuthException' && err.fb_error_message =~ /Code was invalid or expired/
+              return nil
+            else
+              raise
+            end
           end
 
           components.merge(token_info) if token_info
@@ -331,10 +326,15 @@ module Koala
       end
 
       def fetch_token_string(args, post = false, endpoint = "access_token", options = {})
-        Koala.make_request("/oauth/#{endpoint}", {
+        response = Koala.make_request("/oauth/#{endpoint}", {
           :client_id => @app_id,
           :client_secret => @app_secret
-        }.merge!(args), post ? "post" : "get", {:use_ssl => true}.merge!(options)).body
+        }.merge!(args), post ? "post" : "get", {:use_ssl => true}.merge!(options))
+
+        raise ServerError.new(response.status, response.body) if response.status >= 500
+        raise OAuthTokenRequestError.new(response.status, response.body) if response.status >= 400
+
+        response.body
       end
 
       # base 64

data/lib/koala/realtime_updates.rb

@@ -7,19 +7,19 @@ module Koala
       # @note: to subscribe to real-time updates, you must have an application access token
       #        or provide the app secret when initializing your RealtimeUpdates object.
 
-      # The application API interface used to communicate with Facebook. 
-      # @return [Koala::Facebook::API] 
+      # The application API interface used to communicate with Facebook.
+      # @return [Koala::Facebook::API]
       attr_reader :api
       attr_reader :app_id, :app_access_token, :secret
 
-      # Create a new RealtimeUpdates instance.  
-      # If you don't have your app's access token, provide the app's secret and 
+      # Create a new RealtimeUpdates instance.
+      # If you don't have your app's access token, provide the app's secret and
       # Koala will make a request to Facebook for the appropriate token.
-      # 
+      #
       # @param options initialization options.
       # @option options :app_id the application's ID.
       # @option options :app_access_token an application access token, if known.
-      # @option options :secret the application's secret.  
+      # @option options :secret the application's secret.
       #
       # @raise ArgumentError if the application ID and one of the app access token or the secret are not provided.
       def initialize(options = {})
@@ -39,7 +39,7 @@ module Koala
         @api = API.new(@app_access_token)
       end
 
-      # Subscribe to realtime updates for certain fields on a given object (user, page, etc.).  
+      # Subscribe to realtime updates for certain fields on a given object (user, page, etc.).
       # See {http://developers.facebook.com/docs/reference/api/realtime the realtime updates documentation}
       # for more information on what objects and fields you can register for.
       #
@@ -48,11 +48,11 @@ module Koala
       # @param object a Facebook ID (name or number)
       # @param fields the fields you want your app to be updated about
       # @param callback_url the URL Facebook should ping when an update is available
-      # @param verify_token a token included in the verification request, allowing you to ensure the call is genuine 
+      # @param verify_token a token included in the verification request, allowing you to ensure the call is genuine
       #                     (see the docs for more information)
       # @param options (see Koala::HTTPService.make_request)
       #
-      # @return true if successful, false (or an APIError) otherwise.
+      # @raise A subclass of Koala::Facebook::APIError if the subscription request failed.
       def subscribe(object, fields, callback_url, verify_token, options = {})
         args = {
           :object => object,
@@ -60,23 +60,23 @@ module Koala
           :callback_url => callback_url,
         }.merge(verify_token ? {:verify_token => verify_token} : {})
         # a subscription is a success if Facebook returns a 200 (after hitting your server for verification)
-        @api.graph_call(subscription_path, args, 'post', options.merge(:http_component => :status)) == 200
+        @api.graph_call(subscription_path, args, 'post', options)
       end
 
-      # Unsubscribe from updates for a particular object or from updates. 
+      # Unsubscribe from updates for a particular object or from updates.
       #
-      # @param object the object whose subscriptions to delete. 
+      # @param object the object whose subscriptions to delete.
       #               If no object is provided, all subscriptions will be removed.
       # @param options (see Koala::HTTPService.make_request)
       #
-      # @return true if the unsubscription is successful, false (or an APIError) otherwise.
+      # @raise A subclass of Koala::Facebook::APIError if the subscription request failed.
       def unsubscribe(object = nil, options = {})
-        @api.graph_call(subscription_path, object ? {:object => object} : {}, "delete", options.merge(:http_component => :status)) == 200
+        @api.graph_call(subscription_path, object ? {:object => object} : {}, "delete", options)
       end
 
       # List all active subscriptions for this application.
-      # 
-      # @param options (see Koala::HTTPService.make_request) 
+      #
+      # @param options (see Koala::HTTPService.make_request)
       #
       # @return [Array] a list of active subscriptions
       def list_subscriptions(options = {})
@@ -89,12 +89,12 @@ module Koala
       #
       # @param params the request parameters sent by Facebook.  (You can pass in a Rails params hash.)
       # @param verify_token the verify token sent in the {#subscribe subscription request}, if you provided one
-      # 
+      #
       # @yield verify_token if you need to compute the verification token
       #                     (for instance, if your callback URL includes a record ID, which you look up
-      #                     and use to calculate a hash), you can pass meet_challenge a block, which 
+      #                     and use to calculate a hash), you can pass meet_challenge a block, which
       #                     will receive the verify_token received back from Facebook.
-      # 
+      #
       # @return the challenge string to be sent back to Facebook, or false if the request is invalid.
       def self.meet_challenge(params, verify_token = nil, &verification_block)
         if params["hub.mode"] == "subscribe" &&
@@ -111,12 +111,33 @@ module Koala
           false
         end
       end
-      
+
+      # Public: As a security measure, all updates from facebook are signed using
+      # X-Hub-Signature: sha1=XXXX where XXX is the sha1 of the json payload
+      # using your application secret as the key.
+      #
+      # Example:
+      #   # in Rails controller
+      #   # @oauth being a previously defined Koala::Facebook::OAuth instance
+      #   def receive_update
+      #     if @oauth.validate_update(request.body, headers)
+      #       ...
+      #     end
+      #   end
+      def validate_update(body, headers)
+        if request_signature = headers['X-Hub-Signature'] || headers['HTTP_X_HUB_SIGNATURE'] and
+           signature_parts = request_signature.split("sha1=")
+          request_signature = signature_parts[1]
+          calculated_signature = OpenSSL::HMAC.hexdigest('sha1', @secret, body)
+          calculated_signature == request_signature
+        end
+      end
+
       # The Facebook subscription management URL for your application.
       def subscription_path
         @subscription_path ||= "#{@app_id}/subscriptions"
       end
-      
+
       # @private
       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.")

data/lib/koala/version.rb

@@ -1,3 +1,3 @@
 module Koala
-  VERSION = "1.5.0"
+  VERSION = "1.6.0"
 end

data/lib/koala.rb

@@ -3,6 +3,7 @@ require 'digest/md5'
 require 'multi_json'
 
 # include koala modules
+require 'koala/errors'
 require 'koala/api'
 require 'koala/oauth'
 require 'koala/realtime_updates'
@@ -20,8 +21,6 @@ module Koala
   # See http://github.com/arsduo/koala/wiki for a general introduction to Koala
   # and the Graph API.
   
-  class KoalaError < StandardError; end
-
   # Making HTTP requests
   class << self
     # Control which HTTP service framework Koala uses. 

data/readme.md

@@ -13,52 +13,78 @@ Installation
 ---
 
 Easy:
-
-    [sudo|rvm] gem install koala
+```bash
+[sudo|rvm] gem install koala
+```
 
 Or in Bundler:
-
-    gem "koala"
+```ruby
+gem "koala"
+```
 
 Graph API
 ----
-The Graph API is the simple, slick new interface to Facebook's data.  Using it with Koala is quite straightforward:
+The Graph API is the simple, slick new interface to Facebook's data.  
+Using it with Koala is quite straightforward.  First, you'll need an access token, which you can get through 
+Facebook's [Graph API Explorer](https://developers.facebook.com/tools/explorer) (click on 'Get Access Token').  
+Then, go exploring:
 
-    @graph = Koala::Facebook::API.new(oauth_access_token)
-    # in 1.1 or earlier, use GraphAPI instead of API
+```ruby
+@graph = Koala::Facebook::API.new(oauth_access_token)
 
-    profile = @graph.get_object("me")
-    friends = @graph.get_connections("me", "friends")
-    @graph.put_connections("me", "feed", :message => "I am writing on my wall!")
+profile = @graph.get_object("me")
+friends = @graph.get_connections("me", "friends")
+@graph.put_connections("me", "feed", :message => "I am writing on my wall!")
 
-    # three-part queries are easy too!
-    @graph.get_connections("me", "mutualfriends/#{friend_id}")
+# three-part queries are easy too!
+@graph.get_connections("me", "mutualfriends/#{friend_id}")
 
-    # you can even use the new Timeline API
-    # see https://developers.facebook.com/docs/beta/opengraph/tutorial/
-    @graph.put_connections("me", "namespace:action", :object => object_url)
+# you can even use the new Timeline API
+# see https://developers.facebook.com/docs/beta/opengraph/tutorial/
+@graph.put_connections("me", "namespace:action", :object => object_url)
+```
 
 The response of most requests is the JSON data returned from the Facebook servers as a Hash.
 
-When retrieving data that returns an array of results (for example, when calling API#get_connections or API#search) a GraphCollection object will be returned, which makes it easy to page through the results:
+When retrieving data that returns an array of results (for example, when calling `API#get_connections` or `API#search`)
+a GraphCollection object will be returned, which makes it easy to page through the results:
 
-    # Returns the feed items for the currently logged-in user as a GraphCollection
-    feed = @graph.get_connections("me", "feed")
-    feed.each {|f| do_something_with_item(f) } # it's a subclass of Array
-    next_feed = feed.next_page
+```ruby
+# Returns the feed items for the currently logged-in user as a GraphCollection
+feed = @graph.get_connections("me", "feed")
+feed.each {|f| do_something_with_item(f) } # it's a subclass of Array
+next_feed = feed.next_page
 
-    # You can also get an array describing the URL for the next page: [path, arguments]
-    # This is useful for storing page state across multiple browser requests
-    next_page_params = feed.next_page_params
-    page = @graph.get_page(next_page_params)
+# You can also get an array describing the URL for the next page: [path, arguments]
+# This is useful for storing page state across multiple browser requests
+next_page_params = feed.next_page_params
+page = @graph.get_page(next_page_params)
+```
 
 You can also make multiple calls at once using Facebook's batch API:
+```ruby
+# Returns an array of results as if they were called non-batch
+@graph.batch do |batch_api|
+  batch_api.get_object('me')
+  batch_api.put_wall_post('Making a post in a batch.')
+end
+```
+
+You can pass a "post-processing" block to each of Koala's Graph API methods. This is handy for two reasons:
+
+1. You can modify the result returned by the Graph API method:
+
+        education = @graph.get_object("me") { |data| data['education'] }
+        # returned value only contains the "education" portion of the profile
 
-    # Returns an array of results as if they were called non-batch
-    @graph.batch do |batch_api|
-      batch_api.get_object('me')
-      batch_api.put_wall_post('Making a post in a batch.')
-    end
+2. You can consume the data in place which is particularly useful in the batch case, so you don't have to pull
+the results apart from a long list of array entries:
+
+        @graph.batch do |batch_api|
+          # Assuming you have database fields "about_me" and "photos"
+          batch_api.get_object('me')                {|me|     self.about_me = me }
+          batch_api.get_connections('me', 'photos') {|photos| self.photos   = photos }
+        end
 
 Check out the wiki for more details and examples.
 
@@ -67,55 +93,56 @@ The REST API
 Where the Graph API and the old REST API overlap, you should choose the Graph API.  Unfortunately, that overlap is far from complete, and there are many important API calls that can't yet be done via the Graph.
 
 Fortunately, Koala supports the REST API using the very same interface; to use this, instantiate an API:
+```ruby
+@rest = Koala::Facebook::API.new(oauth_access_token)
 
-    @rest = Koala::Facebook::API.new(oauth_access_token)
-    # in 1.1 or earlier, use RestAPI instead of API
-
-  	@rest.fql_query(my_fql_query) # convenience method
-  	@rest.fql_multiquery(fql_query_hash) # convenience method
-  	@rest.rest_call("stream.publish", arguments_hash) # generic version
+@rest.fql_query(my_fql_query) # convenience method
+@rest.fql_multiquery(fql_query_hash) # convenience method
+@rest.rest_call("stream.publish", arguments_hash) # generic version
+```
 
 Of course, you can use the Graph API methods on the same object -- the power of two APIs right in the palm of your hand.
+```ruby
+@api = Koala::Facebook::API.new(oauth_access_token)
 
-    @api = Koala::Facebook::API.new(oauth_access_token)
-    # in 1.1 or earlier, use GraphAndRestAPI instead of API
-
-    @api = Koala::Facebook::API.new(oauth_access_token)
-    fql = @api.fql_query(my_fql_query)
-    @api.put_wall_post(process_result(fql))
-
+@api = Koala::Facebook::API.new(oauth_access_token)
+fql = @api.fql_query(my_fql_query)
+@api.put_wall_post(process_result(fql))
+```
 
 OAuth
 -----
 You can use the Graph and REST APIs without an OAuth access token, but the real magic happens when you provide Facebook an OAuth token to prove you're authenticated.  Koala provides an OAuth class to make that process easy:
-
-    @oauth = Koala::Facebook::OAuth.new(app_id, app_secret, callback_url)
+```ruby
+@oauth = Koala::Facebook::OAuth.new(app_id, app_secret, callback_url)
+```
 
 If your application uses Koala and the Facebook [JavaScript SDK](http://github.com/facebook/facebook-js-sdk) (formerly Facebook Connect), you can use the OAuth class to parse the cookies:
-
-    @oauth.get_user_from_cookies(cookies) # gets the user's ID
-	  @oauth.get_user_info_from_cookies(cookies) # parses and returns the entire hash
-
+```ruby
+@oauth.get_user_from_cookies(cookies) # gets the user's ID
+@oauth.get_user_info_from_cookies(cookies) # parses and returns the entire hash
+```
 And if you have to use the more complicated [redirect-based OAuth process](http://developers.facebook.com/docs/authentication/), Koala helps out there, too:
-
-	  # generate authenticating URL
-	  @oauth.url_for_oauth_code
-	  # fetch the access token once you have the code
-	  @oauth.get_access_token(code)
+```ruby
+# generate authenticating URL
+@oauth.url_for_oauth_code
+# fetch the access token once you have the code
+@oauth.get_access_token(code)
+```
 
 You can also get your application's own access token, which can be used without a user session for subscriptions and certain other requests:
-
-    @oauth.get_app_access_token
-
+```ruby
+@oauth.get_app_access_token
+```
 For those building apps on Facebook, parsing signed requests is simple:
-
-    @oauth.parse_signed_request(signed_request_string)
-
+```ruby
+@oauth.parse_signed_request(signed_request_string)
+```
 Or, if for some horrible reason, you're still using session keys, despair not!  It's easy to turn them into shiny, modern OAuth tokens:
-
-    @oauth.get_token_from_session_key(session_key)
-    @oauth.get_tokens_from_session_keys(array_of_session_keys)
-
+```ruby
+@oauth.get_token_from_session_key(session_key)
+@oauth.get_tokens_from_session_keys(array_of_session_keys)
+```
 That's it!  It's pretty simple once you get the hang of it.  If you're new to OAuth, though, check out the wiki and the OAuth Playground example site (see below).
 
 Real-time Updates
@@ -123,50 +150,50 @@ Real-time Updates
 Sometimes, reaching out to Facebook is a pain -- let it reach out to you instead.  The Graph API allows your application to subscribe to real-time updates for certain objects in the graph; check the [official Facebook documentation](http://developers.facebook.com/docs/api/realtime) for more details on what objects you can subscribe to and what limitations may apply.
 
 Koala makes it easy to interact with your applications using the RealtimeUpdates class:
-
-    @updates = Koala::Facebook::RealtimeUpdates.new(:app_id => app_id, :secret => secret)
-
+```ruby
+@updates = Koala::Facebook::RealtimeUpdates.new(:app_id => app_id, :secret => secret)
+```
 You can do just about anything with your real-time update subscriptions using the RealtimeUpdates class:
+```ruby
+# Add/modify a subscription to updates for when the first_name or last_name fields of any of your users is changed
+@updates.subscribe("user", "first_name, last_name", callback_url, verify_token)
 
-    # Add/modify a subscription to updates for when the first_name or last_name fields of any of your users is changed
-    @updates.subscribe("user", "first_name, last_name", callback_url, verify_token)
-
-    # Get an array of your current subscriptions (one hash for each object you've subscribed to)
-    @updates.list_subscriptions
-
-    # Unsubscribe from updates for an object
-    @updates.unsubscribe("user")
+# Get an array of your current subscriptions (one hash for each object you've subscribed to)
+@updates.list_subscriptions
 
+# Unsubscribe from updates for an object
+@updates.unsubscribe("user")
+```
 And to top it all off, RealtimeUpdates provides a static method to respond to Facebook servers' verification of your callback URLs:
-
-    # Returns the hub.challenge parameter in params if the verify token in params matches verify_token
-    Koala::Facebook::RealtimeUpdates.meet_challenge(params, your_verify_token)
-
+```ruby
+# Returns the hub.challenge parameter in params if the verify token in params matches verify_token
+Koala::Facebook::RealtimeUpdates.meet_challenge(params, your_verify_token)
+```
 For more information about meet_challenge and the RealtimeUpdates class, check out the Real-Time Updates page on the wiki.
 
 Test Users
 -----
 
 We also support the test users API, allowing you to conjure up fake users and command them to do your bidding using the Graph or REST API:
-
-    @test_users = Koala::Facebook::TestUsers.new(:app_id => id, :secret => secret)
-    user = @test_users.create(is_app_installed, desired_permissions)
-    user_graph_api = Koala::Facebook::API.new(user["access_token"])
-    # or, if you want to make a whole community:
-    @test_users.create_network(network_size, is_app_installed, common_permissions)
-
+```ruby
+@test_users = Koala::Facebook::TestUsers.new(:app_id => id, :secret => secret)
+user = @test_users.create(is_app_installed, desired_permissions)
+user_graph_api = Koala::Facebook::API.new(user["access_token"])
+# or, if you want to make a whole community:
+@test_users.create_network(network_size, is_app_installed, common_permissions)
+```
 Talking to Facebook
 -----
 
 Koala uses Faraday to make HTTP requests, which means you have complete control over how your app makes HTTP requests to Facebook.  You can set Faraday options globally or pass them in on a per-request (or both):
-
-    # Set an SSL certificate to avoid Net::HTTP errors
-    Koala.http_service.http_options = {
-      :ssl => { :ca_path => "/etc/ssl/certs" }
-    }
-    # or on a per-request basis
-    @api.get_object(id, args_hash, { :timeout => 10 })
-
+```ruby
+# Set an SSL certificate to avoid Net::HTTP errors
+Koala.http_service.http_options = {
+  :ssl => { :ca_path => "/etc/ssl/certs" }
+}
+# or on a per-request basis
+@api.get_object(id, args_hash, { :timeout => 10 })
+```
 The <a href="https://github.com/arsduo/koala/wiki/HTTP-Services">HTTP Services wiki page</a> has more information on what options are available, as well as on how to configure your own Faraday middleware stack (for instance, to implement request logging).
 
 See examples, ask questions
@@ -184,16 +211,16 @@ Testing
 -----
 
 Unit tests are provided for all of Koala's methods.  By default, these tests run against mock responses and hence are ready out of the box:
-
-    # From anywhere in the project directory:
-    bundle exec rake spec
-
+```bash
+# From anywhere in the project directory:
+bundle exec rake spec
+```
 
 You can also run live tests against Facebook's servers:
-
-    # Again from anywhere in the project directory:
-    LIVE=true bundle exec rake spec
-    # you can also test against Facebook's beta tier
-    LIVE=true BETA=true bundle exec rake spec
-
+```bash
+# Again from anywhere in the project directory:
+LIVE=true bundle exec rake spec
+# you can also test against Facebook's beta tier
+LIVE=true BETA=true bundle exec rake spec
+```
 By default, the live tests are run against test users, so you can run them as frequently as you want.  If you want to run them against a real user, however, you can fill in the OAuth token, code, and access\_token values in spec/fixtures/facebook_data.yml.  See the wiki for more details.

data/spec/cases/api_spec.rb

@@ -65,15 +65,15 @@ describe "Koala::Facebook::API" do
   end
 
   it "executes an error checking block if provided" do
-    body = '{}'
-    Koala.stub(:make_request).and_return(Koala::HTTPService::Response.new(200, body, {}))
+    response = Koala::HTTPService::Response.new(200, '{}', {})
+    Koala.stub(:make_request).and_return(response)
 
     yield_test = mock('Yield Tester')
     yield_test.should_receive(:pass)
 
     @service.api('anything', {}, "get") do |arg|
       yield_test.pass
-      arg.should == MultiJson.load(body)
+      arg.should == response
     end
   end