Facebook Cookbook - Jay Goldman [134]
If you’re not running PHP, check the installation instructions that came with your Client Library.
RESTing with Facebook
Problem
I’m curious to know more about how my app communicates with Facebook. What kind of API is this?
Solution
This is a Representational State Transfer, or REST-like API, which means that calls are simply made over HTTP (using GET or POST) to the Facebook server. You’ll be POSTing requests to http://api.facebook.com/restserver.php when you make calls from your server, but you can visit that URL directly if you’re curious to see what a 101 error response looks like (and who isn’t, really?).
Discussion
The alternative to REST is generally considered to be SOAP, a heavier-weight protocol that includes an additional message layer. The two are very similar in some regards (both generally use HTTP as their transport protocol and generally use XML to encode data), but there’s a lot more overhead in implementing a SOAP-based API. More information about REST and SOAP can be found at http://en.wikipedia.org/wiki/Representational_State_Transfer and http://en.wikipedia.org/wiki/SOAP, respectively.
Storable Data
Problem
I want to make sure that I don’t violate the Facebook Developer Terms of Service. What information am I allowed to retrieve from Platform and store in my own database?
Solution
The (short) list shown in Table 9-1 is all you’re allowed to store.
Table 9-1. Storable data
Property
Description
Uid
User ID
Nid
Network ID
Eid
Event ID
Gid
Group ID
Pid
Photo ID
Aid
Album ID
flid
Friend list ID
listing_id
Marketplace Listing ID
page_id
Page ID
notes_count
Total number of notes written by a user
profile_update_time
Last time the user’s Profile was updated
Discussion
The Developer Terms of Service can be found at http://developers.facebook.com/terms.php.
Authenticating Users
Problem
How do I log a user into my Platform app?
Solution
Users have to be logged into Facebook in order for you to make API calls on their behalf, so Facebook provides an automated authentication process that you can initiate by redirecting users to http://www.facebook.com/login.php?api_key=1234567890&v=1.0 (where 1234567890 is your app’s API key). This URL can accept a few parameters, as documented in the Discussion.
Discussion
The process works like Figure 9-1.
Figure 9-1. User authentication flow
Let’s walk through the steps. Users start off by visiting a Canvas page in your app without logging into Facebook first, as shown in Figure 9-2.
Figure 9-2. Canvas page with login message
You can insert a standard Facebook login button anywhere you’d like with the following code:
where 1234567890 is your app’s API key (which isn’t the same as your app’s ID; the API key can be found in the Facebook Developers app and is usually about 30 characters long, made up of letters and numbers). When users click on that button, they’ll get bumped over to a Facebook login page with your app’s name in it, as in Figure 9-3.
Figure 9-3. Facebook Login page
If this user hasn’t installed your app or agreed to its Terms of Service before, they’ll be shown the ToS page (Figure 9-4).
Figure 9-4. Facebook ToS page
Finally, they’ll be sent to your app’s callback URL, rather than to the page they started on. This is important because the callback URL isn’t actually on Facebook, so you want to use this as an opportunity to store the auth_token variable you’ll get passed and then redirect them to a page in your app:
$auth_token = $_GET['auth_token'];
You’ll need to keep that auth_token handy if you’re going to be making calls into the API from your server to Facebook without rendering them into a Canvas page. Note that auth_tokens expire, but you can create an infinite session instead (see Creating an Infinite Session Key for more info).
The login URL (to which you