Class: Koala::Facebook::API

Inherits:
Object
  • Object
show all
Includes:
GraphAPIMethods, RestAPIMethods
Defined in:
lib/koala/api.rb,
lib/koala/api/graph_collection.rb

Defined Under Namespace

Classes: GraphCollection

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from RestAPIMethods

#rest_call, #set_app_properties

Methods included from GraphAPIMethods

#batch, #debug_token, #delete_connections, #delete_like, #delete_object, #fql_multiquery, #fql_query, #get_comments_for_urls, #get_connection, #get_object, #get_objects, #get_page, #get_page_access_token, #get_picture, #graph_call, #put_comment, #put_connections, #put_like, #put_object, #put_picture, #put_video, #put_wall_post, #search, #set_app_restrictions

Constructor Details

#initialize(access_token = nil, app_secret = nil) ⇒ Koala::Facebook::API

Note:

If no access token is provided, you can only access some public information.

Creates a new API client.

Parameters:

  • access_token (String) (defaults to: nil) —

    access token

  • app_secret (String) (defaults to: nil) —

    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 developers.facebook.com/docs/graph-api/securing-requests/)



18
19
20
21
 
# File 'lib/koala/api.rb', line 18

def initialize(access_token = nil, app_secret = nil)
  @access_token = access_token
  @app_secret = app_secret
end

Instance Attribute Details

#access_token ⇒ Object (readonly)

Returns the value of attribute access_token.



23
24
25
 
# File 'lib/koala/api.rb', line 23

def access_token
  @access_token
end

#app_secret ⇒ Object (readonly)

Returns the value of attribute app_secret.



23
24
25
 
# File 'lib/koala/api.rb', line 23

def app_secret
  @app_secret
end

Instance Method Details

#api(path, args = {}, verb = "get", options = {}, &error_checking_block) { ... } ⇒ Object

Note:

You’ll rarely need to call this method directly.

Makes a request to the appropriate Facebook API.

Parameters:

  • path —

    the server path for this request (leading / is prepended if not present)

  • args (defaults to: {}) —

    arguments to be sent to Facebook

  • verb (defaults to: "get") —

    the HTTP method to use

  • options (defaults to: {}) —

    request-related options for Koala and Faraday. See github.com/arsduo/koala/wiki/HTTP-Services for additional options.

  • error_checking_block —

    a block to evaluate the response status for additional JSON-encoded errors

Options Hash (options):

  • :http_component (Symbol) —

    which part of the response (headers, body, or status) to return

  • :beta (Boolean) —

    use Facebook’s beta tier

  • :use_ssl (Boolean) —

    force SSL for this request, even if it’s tokenless. (All API requests with access tokens use SSL.)

Yields:

  • The response for evaluation

Returns:

  • the body of the response from Facebook (unless another http_component is requested)

Raises:

See Also:



50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
 
# File 'lib/koala/api.rb', line 50

def api(path, args = {}, verb = "get", options = {}, &error_checking_block)
  # we make a copy of args so the modifications (added access_token & appsecret_proof)
  # do not affect the received argument
  args = args.dup

  # If a access token is explicitly provided, use that
  # This is explicitly needed in batch requests so GraphCollection
  # results preserve any specific access tokens provided
  args["access_token"] ||= @access_token || @app_access_token if @access_token || @app_access_token
  if options.delete(:appsecret_proof) && args["access_token"] && @app_secret
    args["appsecret_proof"] = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha256"), @app_secret, args["access_token"])
  end

  # Translate any arrays in the params into comma-separated strings
  args = sanitize_request_parameters(args)

  # add a leading / if needed...
  path = "/#{path}" unless path =~ /^\//

  # make the request via the provided service
  result = Koala.make_request(path, args, verb, options)

  if result.status.to_i >= 500
    raise Koala::Facebook::ServerError.new(result.status.to_i, result.body)
  end

  yield result if error_checking_block

  # if we want a component other than the body (e.g. redirect header for images), return that
  if component = options[:http_component]
    component == :response ? result : result.send(options[:http_component])
  else
    # parse the body as JSON and run it through the error checker (if provided)
    # Note: Facebook sometimes sends results like "true" and "false", which aren't strictly objects
    # and cause MultiJson.load to fail -- so we account for that by wrapping the result in []
    MultiJson.load("[#{result.body.to_s}]")[0]
  end
end