In our continuing “Hello World of APIs” tutorial series we look at Facebook; what a developer needs to know to understand the Facebook API and build an application that integrates with it. As with our first tutorial that used TwitterTrack this API as an example, we have chosen Facebook for obvious reasons: Its huge presence as a social networking service and the fact that an enormous number of apps and websites integrate with the Facebook API to add features that include social updates and interaction, in-game purchasing and social sign-on.
This tutorial will follow the same format as the Twitter tutorial, walking through the steps required to integrate with the Facebook Graph APITrack this API. In the course of the tutorial the following topics will be discussed:
- Application Infrastructure Choices – Why Python?
- Understanding the API – API types, security, etc.;
- Sending the request – Walkthrough of our example application;
The aim of this tutorial is to leave a reader who is familiar with Python with sufficient knowledge to build an application that integrates with the Facebook Graph API.
Application Infrastructure Choices – Why Python?
For this tutorial we will be using Python to build our web application. In another article we discuss the justifications and implications for using Python so please refer to that tutorial for the full discussion.
We have also built a web application (hosted for reference on Github) to demonstrate the integration with the Facebook API using the Flask micro-service framework, coupled with Jinja to provide a HTML-templating utility. We also integrated Google Maps to provide an effective visualization of the data available in the Facebook API.
Understanding the API
As with most API providers, Facebook offers a Developer Center that provides a wealth of information on all its APIs and SDKs. The site includes a myriad of content with details on all its products and APIs. For the purposes of this tutorial we’ll concentrate on the Graph API, which is the entry point for most developers creating applications that integrate with Facebook APIs (Facebook themselves define the Graph API as “the primary way for apps to read and write to the Facebook social graph”).
Facebook have grouped information about the Graph API to make it easy for developers to navigate their site: The key areas are:
- API Explorer
- My Apps
We’ll cover each of these areas in turn.
The starting point for any developer interested in the Graph API is the overview, which provides links to detailed information on the functionality available, examples of HTTP methods and clickable guides for navigating through the resources that make up the Graph API data model. It also provides full documentation on the various Facebook-provided and third party SDKs that are available to developers.
Other pages of particular note are the Securing API requests and Login Security pages that contain information and best practices on how to securely interact with the API and include details on parameters that can be adjusted to help achieve this. The Login Security page also provides a link to information on OAuth-based Access Tokens and their role in applying the appropriate security measures depending on the type of interaction with the Graph API being implemented. This provides important context when it’s time for you to create an app in the My Apps site, as it gives you the knowledge required to adjust the settings of your app appropriately. In the case of this tutorial we focus on User Tokens which are granted as a result of a three-legged OAuth authorization flow, as the majority of the calls to the Graph API that target a specific individual enforce this type of token for authorization.
As with any API integration what you require from the Graph API really depends on what you are aiming to achieve in building an application, but the documentation provides a comprehensive guide to everything you need to know to get started.
Like many API providers, Facebook provides an API Explorer, an interactive tool for exploring the Graph API that allows ad hoc API requests to be executed. The explorer generates a temporary access token specifically for use with the explorer. No other enablement activity is required by new developers in order to use it, but a developer can also choose to use one of the apps they have created as the seed for the access token. Facebook also provides a helpful guide in the overview documentation that walks through how to send a Hello World message with the explorer.
Facebook also provides an access token tool that generates real examples of access tokens for developers’ apps to assist in development and debugging.
As with many API providers, developers must create apps in order to use the Graph API. Apps are logical entities that need to be registered in order to consume the Graph API, and provide an anchor to which security credentials are associated. Facebook provides a console the shows a developer’s apps and also provides a link to create new apps.
On clicking the link the developer is prompted to choice the platform for which they are developing: iOS, Android, Facebook Canvas, or a Website. They also have the option of using advanced setup rather than a wizard.
Choosing a specific platform results in being offered different set-up options by the Quick Start wizard (some of which are related to the use of a Facebook SDK). You can skip the wizard if you choose, but ultimately the result is the same once it’s complete; an app ID and secret are shown in the console, registered under the name of the application that you entered during the enrollment process.
When registration of your app is completed you’ll be presented with the Dashboard page, which shows the App ID and App Secret you’ve just created. You’ll need both these values to be able to make calls to the Graph API, both of which are confidential and should never be shared. Facebook takes precautions to safeguard the value of the App Secret and you’ll need to enter your Facebook password in order to see it in clear text in the browser. The Dashboard also shows the version number of the Graph API that is the oldest the app can access. Any attempt to reference a version older than this will be upgraded to the version shown. Finally, your app is also currently registered in development mode. It is only accessible to you and any user you designate using the Roles menu, and not available to the general public.
From the Dashboard a user can click on the Settings page, which contains the majority of the important settings and information a developer requires in completing their Graph API integration.
The Settings page is split into three separate tabs: Basic, Advanced and Migration. The Basic and Advanced tabs are of particular interest for a developer:
- The Basic tab repeats the App ID and App Secret and presents the opportunity to add some administrative and set-up information.
- The Advanced tab contains information a section on Security and Client OAuth. The settings on this tab will be particularly important later in this tutorial.
The other page of particular interest is Status and Review. You’ll use this page to move your app out of development mode once you are ready. Facebook enforces a review process for apps that are made available to the general public to ensure their quality and adherence to Facebook’s terms and conditions. You need to ensure your app is compliant with these as failing to meet them could result in your app being removed from Facebook.