If there's one catchphrase that's bandied about more than "Web 2.0," these days, it's "social networking." Social networking is based on creating an effectively self-fulfilling site that is almost entirely driven by user content — content that users post on their own accord because, well, all their friends are posting and they don't want to be left out of the fun. MySpace is the ultimate success story in this model, with over 100 million registrations in its first three years, an impressive statistic considering that the site effectively runs itself.

Facebook provides a similar service but in a rather more refined way. It has a smaller, tighter-knit community and better, more efficient tools. And, since August of 2006, Facebook has also provided a programmer interface in the form of a Web-based API, a helpful service that is powerful enough to facilitate some interesting applications. Let's take a closer look.

Getting Started

The Facebook API is REST-based like Flickr's API, meaning that requests are made to Facebook Web services through terse XML messages and responses come back in kind. As is typical for this kind of API, the first step in getting started is heading to the site's developer homepage and signing up for a key to identify yourself and your application.

In this case that site is http://developers.facebook.com, and to get started with the API you need a Facebook account to log in with. Thankfully, Facebook is open to anyone who wants to sign up, so that part is easy enough. After a few clicks, you'll have yourself an API key and a secret key for whatever sort of application you wish to create, whether it be Web-based or something a user has to install on his desktop.

Like many other Web-based APIs, all logins need to be routed through the host Web site. While Web-based apps can simply redirect a user to a Facebook login page before they bounce back into their own interface, client-based applications need to open up a browser and direct the user to login. The URL to use looks like this:

https://api.facebook.com/login.php?api_key=123ABC&auth_token=789XYZ

That results in a page something like Figure 1. The user is asked to authorize the application to access his account. The api_key parameter above is the key created for you at the Developers' page. The auth_token is an ID created by first calling Facebook's createToken service. This is a token used to identify one particular instance of your application as the authentication is taking place.

Once the browser has logged in via the Web page, the token is again used to call the getSession service, again passing in the same api_key and auth_token. Finally, the result from this call is a session key that can be used to make queries against the Facebook site and the user's account.

Using a Wrapper

Of course, all the above calls can be made by POSTing XML directly to Facebook's PHP-based services. However, as is usually the case when dealing with popular XML-based Web services, there are easier ways to go. While Facebook itself only provides the basic XML framework and a wrapper for Java developers, as of this writing wrappers have been written by developers for C#, C++, Perl, PHP, Phython, Ruby, and VB.NET. These wrappers handle the nitty-gritty details of creating and parsing XML messages, as well as handling the actual transmission and receipt thereof.

For this article we use Cosmin Nicolaescu's C# Facebook Framework. His code has seen a few updates to keep up to date with Facebook's minor API changes made since August and it seems reasonably stable. It also provides a suite of classes that represent the various items in Facebook, like people, places, schools, and even jobs, making it straightforward to glean any information required about them.

However, what it's lacking is a straightforward user's guide and example application, which can make using it a little tricky for those with no experience with the Facebook API. To show the basics of using this wrapper, and the Facebook API in general, through the rest of this article I create a simple application called C# FriendViewer that looks like Figure 2.

For the record, I was originally going to call this "C# FaceViewer," but a quick perusal of the Facebook developer forum alerted me that applications relying on the Facebook API are strictly forbidden from using the word "Face" in their title. So, consider yourself warned.

Logging In

As mentioned above, the process of logging in from a client-based application is a three-step process: getting an authentication token, prompting the user to log in via a set URL containing your API key and that auth token, then finally using that token again to get the actual session key that's used for the duration of your application's session.

However, with the C# API wrapper being used here, that process is abstracted down to two steps: opening the browser, then getting the session.

When the application first opens only the Login button is enabled, as shown in Figure 3. At this point, the user hasn't logged in; so, the app can't get a list of his friends. The code to perform that login is very simple:

private void btnLogin_Click(object sender, EventArgs e)
{
    api = new Api("API_KEY", "SECRET_KEY");
    
    try
    {
	api.Open(api.LoginUrl());
    }
    catch (Exception ex)
    { System.Console.WriteLine("Exception: " + ex); }

    btnLogin.Enabled = false;
    btnList.Enabled = true;
}

Api is the class that facilitates interactions with Facebook's site, hiding all the HTTP and XML details. An instance is created using the API key and secret key created at the developer site. The Open() function sends a call to the operating system to open a browser to the given URL, and in this case LoginURL() provides the appropriate URL containing the API key and the token.

Finally, the login button is disabled and the List button is enabled. Since the Open() call blocks, this change won't actually occur until the browser has been opened, which should send this window into the background. The process of going from application to browser and back again is somewhat clumsy from a usability perspective, not to mention slow, but at least it gives your user assurance that you're not doing anything funky with his password.

After the user logs in, he receives a message something like Figure 4, directing him to close the browser and go back to the application:

So, the application can now go ahead and manually retrieve that session key. However, the app has no reliable way of telling that the user actually logged in. You have to rely on the user telling it to go ahead. In the above application, that operation is tied in to the click action from "List Friends," but the call is a simple one:

private void btnList_Click(object sender, EventArgs e)
{
    api.NewSession();
    btnList.Enabled = false;
    listFriends();

}

The first line here is what actually retrieves the session ID from the Facebook site. The key itself is stored internally in your Api instance, so you won't have to worry about it. After that, the app disables the list button, then calls a method to handle the actual querying for the friend's data.