Facebook Cookbook - Jay Goldman [132]
Time to dig into the Facebook Application Programming Interface (API). If you’re unfamiliar with the concept of an API, read the first few recipes in this chapter carefully. The majority of the content here will cover the various API calls and how to get different types of data in and out of Facebook, with some extra attention at the end to some of the new beta features that have recently been introduced. As with the rest of this book, I’m going to cover the API using the official Facebook PHP Client, but it shouldn’t be too hard to convert these examples into your language of choice.
NOTE
In the interest of saving space (and trees!), I’ve omitted the code to set up a Facebook Client object and retrieve the active user from most of the recipes in this chapter. Since it’s always the same, refer to What’s an API? for reference.
You should be able to look up any of the API calls covered in this chapter by adding them to the end of the Facebook Developers Wiki URL. As an example, if you want more info on Users.getInfo(), go to http://wiki.developers.facebook.com/index.php/Users.getInfo.
What’s an API?
Problem
I keep hearing about this API thing. API this, API that. What’s the deal?
Solution
According to Wikipedia:
An application programming interface (API) is a source code interface that an operating system, library, or service provides to support requests made by computer programs.
In the case of Facebook, the API provides developers with external access to the very core functionality of Platform, in a way that enables you to build on top of it and integrate it directly into your application. All of the other pieces of Platform—FBML, FBJS, FQL, etc.—wouldn’t exist without the API, but that’s not true the other way around. There are lots of examples of really powerful APIs in web applications that exist without any means to do frontend development on top of them (see the upcoming Discussion for some examples).
Most APIs exist as a specification that explains what you can expect to receive back from a service when you make certain calls to it. The Facebook API is no different, and you can visit http://wiki.developers.facebook.com/index.php/API to see all of the API calls available and what they expect to receive from you and send back to you (e.g., Pages.isFan() expects a page_id and a uid and returns XML containing either 0 for false or 1 for true). Luckily for you, Facebook has gone a little beyond the norm by also providing a full Client Library, which makes it easy to integrate API code into your application (see Getting Started with the Client Library for more info).
Generally speaking, you make a call to an API directly in your code and then use the response as you would any other variable. A quick example:
include_once 'resources/includes/config.php';
include_once 'resources/includes/facebook.php';
global $api_key, $secret;
$facebook = new Facebook($api_key, $secret);
$facebook->require_frame();
$user = $facebook->require_login();
$fields = array('last_name', 'first_name');
$myUser = $facebook->api_client->users_getInfo($user, $fields);
echo $myUser[0]['first_name'] . ' ' . $myUser[0]['last_name'];?>
The end result of this code should be the current loggedinuser’s first name and last name separated by a space. Although this looks like a lot of code to get to that point, keep in mind that the first five lines are setup, which you need to do only once per page. Since this is our first actual, live code sample from the API, let’s take a look at what we’re doing in each section:
include_once 'resources/includes/config.php';
include_once 'resources/includes/facebook.php';
global $api_key, $secret;
The config.php file includes the definition of the api_key and secret variables, which hold the API and secret keys for your application (you can find them in the Developers app, on your app’s page: http://www.facebook.com/developers/apps.php?app_id=12345, where 12345 is your app’s ID). You don’t have to set up your app that way,