Getting Started: The Graph API

The Graph API is the primary way to get data in and out of Facebook's social graph. It's a low-level HTTP-based API that you can use to query data, post new stories, create check-ins or any of the other tasks that an app might need to do. Facebook's Open Graph allows you to define new objects and actions in a user's social graph, and the way that you create new instances of those actions and objects is via the Graph API.

The Graph API is also the underlying mechanism that's used by Facebook's iOS, Android, PHP and JavaScript toolkits. It's used by many of the third-party toolkits that exist for other languages. Many people use those higher-level toolkits because they abstract away common actions, but if you want to read or write data out of the graph, you will end up using the Graph API.

The social graph itself is a graph in the computer science sense. It's not a simple table of data. It's a series of nodes which all connect to each other. This document is meant as an introduction about how to not only query nodes in the graph, but also how you can query connections between nodes in the graph. Those connections are what let you post to a user's timeline, create location check-ins or work with a user's photos. So understanding when you need a node and when you need to create a connection is an important distinction.

An important note that one other API to access the social graph exists at Facebook. FQL has roughly equivalent functionality with the Graph API but presents the same set of APIs through an SQL-like interface. To use FQL you will need to know the basics of the Graph API since the FQL endpoints follow the Graph API. So it's still best to learn the Graph API, even if you prefer to use FQL.

Why Learn the Graph API?

Facebook's primary value to app vendors is three-fold:

First, Facebook represents an excellent distribution path for people building apps. If your app is a game it can post achievements to Facebook. Your app can post about the length of the user's latest run or it can generate a check-in. Those posts are seen by friends and they might be willing to try your app out. The Open Graph is a great way for people to find out about your app or business.
Second, Facebook's social graph makes it possible to build more engaging and sticky apps since you can finally add a social context to your app. Friends can be part of the fun.
Third, using Facebook Login lowers the barrier for people to sign into your app and is an identity that works across all devices.

This context matters, since each of these interactions with people happen through Facebook's Graph API.

The Graph API Explorer

The easiest way to understand the Graph API is to explore it with the Graph API Explorer. The Graph API Explorer is a low-level tool you can use to query, add and remove data. It's a very useful resource while you're building your app.

Open the Graph API Explorer. If you have a Facebook account and you're logged into Facebook when you first load the Explorer you will see a single node displayed in the output with only two fields set. That node is your personal node in the Graph API. Two fields are selected, id and name. The data that you see is public data. (Later on, we'll see how to request data that requires explicit permission to read.)

The two pieces of data that you see are your id node in the graph and your name. Try de-selecting the id and name attributes from the left hand side and then click the Submit button.

You will get - depending on your privacy settings - more data back, including your gender, location and a link to your profile. These are the default values that are returned when no fields are selected.

At this point we should point out a few things:

Everything in the Open Graph has an ID.

You'll notice that the path that's selected is in the form of /<your facebook id>. This is how you can make an API call that addresses any item in the graph that you have permission to reach. In the Graph API Explorer the results can contain links to other items.

The Graph API Explorer directly maps your action directly into an HTTP request.

The Graph API is driven by HTTP requests. HTTP methods tend to map directly to actions on the graph. GET for read, POST for modify & add and DELETE to remove nodes. In the Explorer you can select the method on the left (GET, POST or DELETE), the path in the main text area (/ID) and any modifiers to the request (fields=id,name). These same methods are what you use from any HTTP client, including your web browser.

This is the original call that we made from the Explorer, mapped to an HTTP request:

(Note: some headers have been omitted from this example to improve clarity.)

GET /774635482?fields=id%2Cname HTTP/1.1
Host: graph.facebook.com
Connection: close

HTTP/1.1 200 OK
Content-Type: text/javascript; charset=UTF-8
Expires: Sat, 01 Jan 2000 00:00:00 GMT
Date: Thu, 11 Oct 2012 17:28:02 GMT
Connection: close
Content-Length: 48

{"id":"774635482","name":"Christopher Blizzard"}

This is a GET, which reads data. The path is /774635482, which maps to a resource in the graph. It also includes an encoded version of the query string ?fields=id,name after the path, which modifies what is returned.

When you make a call from JavaScript with JS.api or from PHP with the Facebook::API call, that request is mapped directly to an HTTP path on graph.facebook.com.

Names

So far we've only talked about how to access nodes in the graph by ID. There are two types of objects that can also be accessed by name: People and Pages.

In our example above, we accessed a person with the path /774635482. You could have also used the name that is associated with that ID: /christopher.blizzard.

There's also one special path that's worth mentioning: /me. As you might imagine, /me maps to your identity and we'll use it later. However, accessing it requires that we authenticate, and we haven't discussed authentication yet, so trying to access it will return an error. We'll come back to /me later.

Logging into Facebook and presenting an identity is core to many of the APIs and functions that we'll be talking about. What we'll cover in this document is a small subset of what Facebook Login does so that you can understand it in the context of the Graph API. But once you've gone through this document, you should check out the full set of documents on Facebook Login.

Here is a small glossary of terms that are useful for understanding data access through the Graph API:

Login: Facebook Login is a service and set of tools that Facebook offers to developers. It's included in our developer toolkits for iOS, Android as well as our JS and PHP toolkits. Developers can integrate logging in with Facebook in Mobile apps, Web apps or Facebook canvas apps. If you want to implement an app that integrates with Facebook's data and users you need to use Facebook Login.
Authorization: In order to use Facebook Login, even for just a simple login on a website, a person must assert that they allow you to have access to their information. Authorization is an application flow that confirms that it's OK for you to access someone's data. That flow requires the participation of the client (mobile or web), your servers (if you have them) and Facebook's servers. The most common use cases are built into our pre-built toolkits, including flow and built-in dialogs. But if you have a server component, some integration will be required for one of the callbacks from the auth flow.
Permissions: Permissions are what you ask for when a person Authorizes through Facebook Login. Facebook implements a wide set of permissions that range from basic, which allows you access a user's public profile and friend list, to extended permissions which let you publish actions to a user's open graph (and their Timeline by effect.) We'll cover a couple of the permissions here, but there are a large number of permissions you can ask for. A couple of examples of permissions are manage_pages or publish_actions.
Access Token: You'll hear a lot about access tokens. The access token is an opaque string that is generated at the end of the authorization process. It represents a set of permissions that have been granted, and can be used in the context of a specific app and a specific person. Every (authenticated) request that you make to the Graph API will require passing along the access token. Some side notes on access tokens that are worth mentioning: Access tokens expire, so your application will have to handle refreshing them when they time out. And in addition to there being an access token that lets you work with a person's data, you can also request an access token that operates on a page or an app. The page token is used to manage open graph data for a specific Facebook page. An app access token gives you access to app-specific data like app analytics.

Now that we've talked about the basic concepts involved in Login, Authorization & Permissions, let's see how it works in the context of the Graph API explorer.

Open the Graph API Explorer and click the button that says "Get Access Token" and then come back here. Once you click it we're going to walk through each thing you see and see how it relates to the concepts we've talked about.

If you're not logged into Facebook, the first thing that you're going to see is a dialog that says you need to log into Facebook. Click 'Okay' and log into Facebook. You'll be brought back to the Explorer, but you'll need to press the Get Access Token button again.

So now that you're logged in and you've pressed the button you're going to get a dialog that looks like this:

This dialog exists so that you can pick the permissions you want before you start the authorization request. What permissions you want to request depends on what data you want access to or what you might want to post. This dialog is only part of the Explorer app, so people using your app will never see anything like this.

The best practice for what permissions to ask for is that you should only ask for the permissions you need right now. That is, it's possible to ask for some read-only permissions to start with and later you can ask for write permissions once the person using your app is ready to publish something.

These permissions are passed along directly as part of the first authorization query as a set of strings. Permissions aren't managed in the app's dashboard. They are managed as part of the initial request.

In this dialog you can see three different types of permissions:

User Data Permissions. This is data about the person, and is read-only.
Friend's Data Permissions. This is data about a person's friends and permissions pretty much map to the user data permissions, just applying to friends instead of the person.
Extended Permissions. These are permissions that give you deeper access to a person's data or lets you write to a someone's open graph. They are also optional - a person can say no to an extended permission. And they can also change that permission decision later in their privacy settings.

In addition to the main three kinds of permissions there are two additional settings which are not covered in this document: pages and apps. Those are used for access to things required to manage pages on Facebook and internal APIs for managing apps.

For the sake of this walk-through, lets pick two permissions: user_likes and user_photos.

When you click "Get Access Token" again, you'll get the Login Dialog on facebook.com. It looks like this:

What's happened so far is that the Explorer app has passed along your request for those two permissions. Facebook then asks the person (you in this case) if it's OK for the app to have access to those two extra permissions. (Your basic info is included by default.)

When you click Log In with Facebook, an authorization token will be generated and the Graph API Explorer will use it in subsequent requests to the Graph API. In fact, when you return to the Graph API Explorer, the auth token field should be filled in. Clicking the 'Debug' button will show you the App ID, User ID, when it expires and the permission scope for it.

One very important note on privacy that's relevant to developers. Facebook offers a large number of controls to people about what data they would like to share with friends, but they can also control what they choose to share with apps. This means that even if you ask for a permission, there's a chance you still won't be able to see the data you're asking for. One person might be sharing their birthday, and another may not. You need to build your application so that it can handle these differences. We take people's privacy very seriously at Facebook which means that people are the final arbiter for what will be shared and what will not be. As a developer, you should be aware that there will be differences in what people will share and what they won't.

A good overview of these capabilities is part of the 'Other websites and applications' section of Facebook's Data User Policy. It's very human-readable, and it's worth spending time with.

Back to the task at hand. Now that we have an access token and understand how it works we can move on to talking about one of the most important parts of the Graph API: Connections.

Connections

Now that we've talked about how to log in, we've authorized some data access and we've got an access token, it's time to talk about the data we can look at, in particular connections.

The first thing you should do in the Explorer is load the special /me path. We mentioned this earlier, but it's a special node in the graph that relates to you as the user. When you load it you should see something like this:

Scroll through some of the data to have a look at what you can see. You should see things like name, location, work history, some information on favorites, education, etc. One thing you should notice is that many of the objects in the returned data are actually links. Click on an ID in the location data, for example, and you'll be taken to that object's information.

But since you set up permissions for both photos and likes, where is that data? It's not listed in your /me entry.

The answer can be revealed with a special URL through the Graph API. At the end of your entry add a ?metadata=1 at the end. You'll notice if you scroll down that there are a bunch of metadata entries for the fields that are available on your object as well as a set of connections. All of those connections are hyperlinks, and you can just click on them to load them.

The way to access a connection is by adding it after the object that is the source of the connections. For example, if you want to see a list of friends, load /me/friends. It's as simple as that.

One thing you should realize is that even though a connection is listed in the metadata it doesn't mean that you have access to see the data behind it. The metadata is a complete list of connections, irrespective of the permissions that you've requested. For an example, have a look at the entry for /me/notes. Even if you had posted some notes, it would return an empty set of data.

If you've got notes as part of your profile, you need to add the user_notes permission in order to see them. If you want to add the user_notes permission to your access token, it's pretty easy. Click on 'Get Access Token', look for the user_notes permission on the 'User Data Permissions' pane, click it and add it. You'll get an extra dialog from Facebook about adding that permission. Say yes and you'll see any notes you have listed.

Let's talk about the way that we can use connections to query data in the API in a more useful way. Since you asked for the permission for user_photos one of the things you should be able to see are albums

Load the list of albums in the Explorer at the /me/albums end point.
In that list, find your list of Timeline Photos. Click on its ID and that should load the information about that album into the explorer.
On the left hand side, click on the '+' under the Node: [id] bit. You'll notice that there are a number of fields that you can select from there. Scroll to the bottom for connections and select 'Photos.'

Click Submit and the explorer should be able to load the list of photos in that album. This is the way that you can explore the connections and nodes in someone's graph. You'll notice that the url changed to something like /album-node-number?fields=photos. You can select a bunch of different fields when making a query - try adding likes or comments to the query and you can see them show up as well.

Next Steps

From here you should be able to navigate data in the graph, but there's a lot more that's available in the Graph API. It's possible to publish stories with Open Graph, delete nodes or search the graph. There's also a real-time API, a batch API and a way to get get more than one query answered with a single call. There are other advanced functions that are worth looking into, especially if you're going to be building a large application that works with Facebook. The best place to do that is start with the Facebook Graph API Reference.

Updated about a week ago