REST API

The Graph API is Facebook’s new hotness, faster and niftier and pretty much better in all ways than what came before. That said, though, it’s not yet complete: certain tasks, such as application management, still require you to use the traditional REST API.

API Changes in 1.2beta

With Koala 1.2beta, we’re consolidating all the API classes into Koala::Facebook::API. The GraphAndRestAPI class proved it’s easy to provide access to both the Graph and REST APIs in a single class, so there’s no reason to provide three classes when one would do. Don’t worry — this is a non-breaking change — the old GraphAPI, RestAPI, and GraphAndRestAPI classes are all aliased to API (with a deprecation warning).

Koalas in the REST API

Fortunately for all of us, Koala supports the REST API. In 1.2beta and beyond, REST API methods are built into the central API class; pre-1.2beta, you can use either the RestAPI class or the GraphAndRestAPI class, which (like the API class in 1.2) allows all-in-one access to the old and the new.

All API classes are instantiated the same way:

@rest = Koala::Facebook::RestAPI.new(oauth_access_token) # pre-1.2beta
@rest = Koala::Facebook::API.new(oauth_access_token) # 1.2beta and beyond

Koala provides a generic API interface named rest_call, which takes the name of a method and its arguments (very similar to the [Javascript SDK’s api method](http://developers.facebook.com/docs/reference/javascript/FB.api/):

@rest.rest_call("stream.publish", arguments_hash)

We also provide FQL query and multiquery wrappers:

@rest.fql_query("select name from user where uid = 2905623")
# => [{"name"=>"Alex Koppel"}]
@rest.fql_multiquery(
 :query1 => "select first_name from user where uid = 2905623",
 :query2 => "select first_name from user where uid = 2901279"
)
# => {"query1" => [{"first_name" => "Alex"}], "query2" => [{"first_name" => "Luke"}]}

We’re going to provide additional convenience methods soon to fill out the gaps in the Graph API. (As Graph API equivalents are provided, we’ll add deprecation warnings but will not remove the convenience methods.)

1 + 1 =

You can do some cool things when you combine the two APIs, as in this example from the OAuth Playground:

# say we only know the access token but not the user's ID
@rest = Koala::Facebook::GraphAndRestAPI.new(oauth_access_token) # pre-1.2beta
@rest = Koala::Facebook::API.new(oauth_access_token) # 1.2beta and beyond
result = @rest.get_object("me")
uid = result["id"]
# now, get all the permissions through FQL
permissions = @rest.fql_query("select #{all_permissions.join(",")} from permissions where uid = #{uid.to_s}")
# => [{"read_stream"=>1, "publish_stream"=>1}]
# of course, now you can do this in one call with the [[Batch API]]

api-read

We support Facebook’s api-read server for all read-only calls — speed is important, and those servers are faster.