class Koala::Facebook::API

Attributes

access_token[R]
app_secret[R]

Public Class Methods

new(access_token = Koala.config.access_token, app_secret = Koala.config.app_secret) click to toggle source

Creates a new API client. @param [String] access_token access token @param [String] app_secret app secret, for tying your access tokens to your app secret

If you provide an app secret, your requests will be
signed by default, unless you pass appsecret_proof:
false as an option to the API call. (See
https://developers.facebook.com/docs/graph-api/securing-requests/)

@note If no access token is provided, you can only access some public information. @return [Koala::Facebook::API] the API client

   # File lib/koala/api.rb
18 def initialize(access_token = Koala.config.access_token, app_secret = Koala.config.app_secret)
19   @access_token = access_token
20   @app_secret = app_secret
21 end

Public Instance Methods

api(path, args = {}, verb = "get", options = {}) click to toggle source

Makes a request to the appropriate Facebook API. @note You'll rarely need to call this method directly.

@see GraphAPIMethods#graph_call

@param path the server path for this request (leading / is prepended if not present) @param args arguments to be sent to Facebook @param verb the HTTP method to use @param options request-related options for Koala and Faraday.

See https://github.com/arsduo/koala/wiki/HTTP-Services for additional options.

@option options [Symbol] :http_component which part of the response (headers, body, or status) to return @option options [Symbol] :format which request format to use. Currently, :json is supported @option options [Symbol] :preserve_form_arguments preserve arrays in arguments, which are

expected by certain FB APIs (see the ads API in particular,
https://developers.facebook.com/docs/marketing-api/adgroup/v2.4)

@option options [Boolean] :beta use Facebook's beta tier @option options [Boolean] :use_ssl force SSL for this request, even if it's tokenless.

(All API requests with access tokens use SSL.)

@raise [Koala::Facebook::ServerError] if Facebook returns an error (response status >= 500)

@return a Koala::HTTPService::Response object representing the returned Facebook data

    # File lib/koala/api.rb
 87 def api(path, args = {}, verb = "get", options = {})
 88   # we make a copy of args so the modifications (added access_token & appsecret_proof)
 89   # do not affect the received argument
 90   args = args.dup
 91 
 92   # If a access token is explicitly provided, use that
 93   # This is explicitly needed in batch requests so GraphCollection
 94   # results preserve any specific access tokens provided
 95   args["access_token"] ||= @access_token || @app_access_token if @access_token || @app_access_token
 96 
 97   if options.delete(:appsecret_proof) && args["access_token"] && @app_secret
 98     args["appsecret_proof"] = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha256"), @app_secret, args["access_token"])
 99   end
100 
101   # Translate any arrays in the params into comma-separated strings
102   args = sanitize_request_parameters(args) unless preserve_form_arguments?(options)
103 
104   # add a leading / if needed...
105   path = "/#{path}" unless path =~ /^\//
106 
107   # make the request via the provided service
108   result = Koala.make_request(path, args, verb, options)
109 
110   if result.status.to_i >= 500
111     raise Koala::Facebook::ServerError.new(result.status.to_i, result.body)
112   end
113 
114   result
115 end
graph_call(path, args = {}, verb = "get", options = {}, &post_processing) click to toggle source

Make a call directly to the Graph API. (See any of the other methods for example invocations.)

@param path the Graph API path to query (no leading / needed) @param args (see get_object) @param verb the type of HTTP request to make (get, post, delete, etc.) @options (see get_object)

@yield response when making a batch API call, you can pass in a block

that parses the results, allowing for cleaner code.
The block's return value is returned in the batch results.
See the code for {#get_picture} for examples.
(Not needed in regular calls; you'll probably rarely use this.)

@raise [Koala::Facebook::APIError] if Facebook returns an error

@return the result from Facebook

   # File lib/koala/api.rb
44 def graph_call(path, args = {}, verb = "get", options = {}, &post_processing)
45   # enable appsecret_proof by default
46   options = {:appsecret_proof => true}.merge(options) if @app_secret
47   response = api(path, args, verb, options)
48 
49   error = GraphErrorChecker.new(response.status, response.body, response.headers).error_if_appropriate
50   raise error if error
51 
52   # if we want a component other than the body (e.g. redirect header for images), provide that
53   http_component = options[:http_component]
54   desired_data = if options[:http_component]
55     http_component == :response ? response : response.send(http_component)
56   else
57     # turn this into a GraphCollection if it's pageable
58     API::GraphCollection.evaluate(response, self)
59   end
60 
61   # now process as appropriate for the given call (get picture header, etc.)
62   post_processing ? post_processing.call(desired_data) : desired_data
63 end

Private Instance Methods

check_response(http_status, body, headers) click to toggle source
    # File lib/koala/api.rb
141 def check_response(http_status, body, headers)
142 end
preserve_form_arguments?(options) click to toggle source
    # File lib/koala/api.rb
137 def preserve_form_arguments?(options)
138   options[:format] == :json || options[:preserve_form_arguments] || Koala.config.preserve_form_arguments
139 end
sanitize_request_parameters(parameters) click to toggle source

Sanitizes Ruby objects into Facebook-compatible string values.

@param parameters a hash of parameters.

Returns a hash in which values that are arrays of non-enumerable values

(Strings, Symbols, Numbers, etc.) are turned into comma-separated strings.
    # File lib/koala/api.rb
125 def sanitize_request_parameters(parameters)
126   parameters.reduce({}) do |result, (key, value)|
127     # if the parameter is an array that contains non-enumerable values,
128     # turn it into a comma-separated list
129     # in Ruby 1.8.7, strings are enumerable, but we don't care
130     if value.is_a?(Array) && value.none? {|entry| entry.is_a?(Enumerable) && !entry.is_a?(String)}
131       value = value.join(",")
132     end
133     result.merge(key => value)
134   end
135 end