There is something infinitely cool about seeing all your friends listed in an associative array. The Facebook API gives you exactly that kind of capability. For the 2011 Camp Hackathon competition at the university my team put together an application that allows for real-time collaborative composition of music. A key part of this app was the ability to invite your friends right into your “jam session” using the Facebook Requests API, and running the app inside of a Facebook canvas to make use of the social features that allow for apps to spread quickly within the Facebook ecosystem.

My primary role on the team was creating the server-side elements that allowed for real-time communication between clients, and the interactions with the Facebook API. I had never used the Facebook API before and as I submersed myself in it I picked out a couple things that weren’t obvious upon first inspection. The purpose of this post today is to guide you through the learning process I went through, to clarify a few points, and ensure that you can get up and running much quicker than I did. I recommend starting by taking a quick look through the developer docs, they are constantly changing and likely have been updated since the time I published this article, you can find them here on the Facebook developers site.

The Big Picture

To someone just starting out with this API, here’s the overview. There are a couple disjoint pieces that all come together, each one exists separately:

• OAuth2.0 Authentication – This gives you access to the user’s data and information. You perform a request for Facebook permissions and what is returned to you is an access_token which serves as your OAuth ID for performing API calls, together with your app’s secret and ID.
• Server-side Facebook API – This is facilitated via cURL requests to the graph URLs. Facebook has created a wrapper in the form of a class that will perform all of these interactions for you. This is the API you will use to do things such as look up user profile data and get lists of likes and friends for processing server-side with PHP.
• Client-side Javascript Libraries - These are provided by Facebook and give you access to rich UI features such as dialogs. In our app we use the client-side library to display the Request Dialog.

Both the server-side and client-side API require a valid access_token, returned from the OAuth dialog. In our application we performed server-side authentication, saved the access_token in a cookie using the Facebook PHP API, and passed it to client-side Javascript as necessary.

Today we will accomplish three things with these APIs:

1. Prompt the user to give our app proper permissions via the OAuth Dialog, using the Javascript libraries.
2. Retrieve the user’s fbid using the server-side APIs to uniquely identifying them in our application, and to access their basic profile data.
3. Allow the user to invite friends to join them in our app using the Request Dialog, and handle matching these requests up when the recipient user accepts.

Read the rest of this entry »