Thursday, June 28, 2012

Graph API

At Facebook's core is the social graph; people and the connections they have to everything they care about. The Graph API presents a simple, consistent view of the Facebook social graph, uniformly representing objects in the graph (e.g., people, photos, events, and pages) and the connections between them (e.g., friend relationships, shared content, and photo tags).
Every object in the social graph has a unique ID. You can access the properties of an object by requesting https://graph.facebook.com/ID. For example, the official page for the Facebook Platform has id 19292868552, so you can fetch the object at https://graph.facebook.com/19292868552:
{
   "name": "Facebook Platform",
   "website": "http://developers.facebook.com",
   "username": "platform",
   "founded": "May 2007",
   "company_overview": "Facebook Platform enables anyone to build...",
   "mission": "To make the web more open and social.",
   "products": "Facebook Application Programming Interface (API)...",
   "likes": 449921,
   "id": 19292868552,
   "category": "Technology"
}
Alternatively, people and pages with usernames can be accessed using their username as an ID. Since "platform" is the username for the page above, https://graph.facebook.com/platform will return what you expect. All responses are JSON objects.
All objects in Facebook can be accessed in the same way:
All of the objects in the Facebook social graph are connected to each other via relationships. Bret Taylor is a fan of the Coca-Cola page, and Bret Taylor and Arjun Banker are friends. We call those relationships connections in our API. You can examine the connections between objects using the URL structure https://graph.facebook.com/ID/CONNECTION_TYPE. The connections supported for people and pages include:
We support different connection types for different objects. For example, you can get the list of all the people attending the Facebook Developer Garage at SXSW (ID #331218348435) by fetching https://graph.facebook.com/331218348435/attending?access_token=....
All of the different types of objects and connections we support are included in the Graph API reference documentation. The easiest way to get started is to check out the Graph API Explorer.

Authorization

The Graph API as such allows you to easily access all public information about an object. For example, https://graph.facebook.com/btaylor (Bret Taylor) returns all the public information about Bret. For example a user's first name, last name and profile picture are publicly available.
To get additional information about a user, you must first get their permission. At a high level, you need to get an access token for the Facebook user. After you obtain the access token for the user, you can perform authorized requests on behalf of that user by including the access token in your Graph API requests:
https://graph.facebook.com/220439?access_token=...
For example https://graph.facebook.com/btaylor?access_token=... (Bret Taylor) returns additional information about Bret Taylor.
The Graph API uses OAuth 2.0 for authorization. Please read the authentication guide which provides details of Facebook's OAuth 2.0 implementation, how to request permissions from a user and obtain an access token.
Getting an access token for a user with no extended permissions allows you to access the information that the user has made available to everyone on Facebook. If you need specific information about a user, like their email address or work history, you must ask for the specific extended permissions. The reference documentation for each Graph API object contains details about the permissions you need to access each connection and property on that object.

Page Login

You can impersonate pages administrated by your users by requesting the manage_pages permission.
Once a user has granted your application the "manage_pages" permission, the "accounts" connection will allow you to access the list of pages a user administers as well as retrieve an access_token for each of those pages. See the Page Authentication documentation for more information.

App Login

To make administrative calls that do not require an active user (for example, retrieving analytics data or test users) you need to obtain an access token for your app. Read more about how to get an app access token in the Authenticating as an App documentation.

Reading

The Graph API allows you to read properties and connections of the Facebook social graph. You can use the API to read specific fields, get pictures of any object, introspect an object for metadata and get real-time updates on any changes.

Selection

By default, most object properties are returned when you make a query. You can choose the fields (or connections) you want returned with the "fields" query parameter. For example, this URL will only return the id, name, and picture of Ben: https://graph.facebook.com/bgolub?fields=id,name,picture
You can also request multiple objects in a single query using the "ids" query parameter. For example, the URL https://graph.facebook.com?ids=arjun,vernal returns both profiles in the same response.
The "ids" query parameter also accepts URLs. This is useful for finding IDs of URLs in the Open Graph. For example: https://graph.facebook.com/?ids=http://www.imdb.com/title/tt0117500/
Additionally, there is a special identifier me which refers to the current user. So the URL https://graph.facebook.com/me returns the active user's profile.
When retrieving Posts via the /home, /feed, or /posts connection, you can restrict the results to only those with a location attached by adding with=location to the URL parameters:
https://graph.facebook.com/me/home?with=location

Pictures

You can render the current profile photo for any object by adding the suffix /picture to the object URL. For example, this will render your public profile photo:
<img src="https://graph.facebook.com/vpakajeff/picture"/>
The same URL pattern works for all objects in the graph:
You can specify the picture size you want with the type argument, which should be one of square (50x50), small (50 pixels wide, variable height), normal (100 pixels wide, variable height), and large (about 200 pixels wide, variable height): https://graph.facebook.com/vpakajeff/picture?type=large.
If you need a picture to be returned over a secure connection, you can set the return_ssl_resources argument to 1: https://graph.facebook.com/vpakajeff/picture?return_ssl_resources=1.

Paging

When querying connections, there are several useful parameters that enable you to filter and page through connection data:

Dates

All date fields are returned as ISO-8601 formatted strings. You can optionally override the date format by specifying a "date_format" query parameter. The accepted format strings are identical to those accepted by the php date function. For example, https://graph.facebook.com/platform/feed?date_format=U returns the Platform page's feed, with unixtime-formatted dates.

Introspection

The Graph API supports introspection of objects, which enables you to see all of the connections an object has without knowing its type ahead of time. To get this information, add metadata=1 to the object URL, and the resulting JSON will include a metadata property that lists all the supported connections for the given object. For example, you can see all the connections for the Developer Garage event above by fetching https://graph.facebook.com/331218348435?metadata=1. That outputs:
{
   "name": "Facebook Developer Garage Austin - SXSW Edition",
   "metadata": {
      "connections": {
         "feed": "https://graph.facebook.com/331218348435/feed",
         "picture": "https://graph.facebook.com/331218348435/picture",
         "invited": "https://graph.facebook.com/331218348435/invited",
         "attending": "https://graph.facebook.com/331218348435/attending",
         "maybe": "https://graph.facebook.com/331218348435/maybe",
         "noreply": "https://graph.facebook.com/331218348435/noreply",
         "declined": "https://graph.facebook.com/331218348435/declined"
      }
   }
}
The introspection feature is a useful and extensible way to find all the things your users are connected to.

Real-Time updates

Real-time updates provide you the ability to receive updates about all of your application's users, as their data changes. With such subscriptions, you can be confident that your cached data is correct without polling Facebook's servers, increasing the reliability of your application, and the responsiveness of your user experience.

Searching

You can search over all public objects in the social graph with https://graph.facebook.com/search. The format is:
https://graph.facebook.com/search?q=QUERY&type=OBJECT_TYPE
We support search for the following types of objects:
You can restrict the fields returned by these searches using the ?fields= URL parameter, in the same way you can when reading other objects. For example, to get only the names of events, you can do the following:
Some fields such as id, and start_time for events, are always returned.
You can also search an individual user's News Feed, restricted to that user's friends, by adding a q argument to the home connection URL:
Note: /me/home retrieves an outdated view of the News Feed. This is currently a known issue and we don't have any near term plans to bring them back up into parity.
When searching for public posts or posts on the user's News Feed, you can page over the results by using the since, until and limit parameters. since and until both accept a unix timestamp. When paging back in time, you should use until in conjunction with limit where until is the unixtime value of the created_time field in the last object returned by your previous query. When paging forward in time you should set since to be the unixtime value of the created_time field in the first object returned by your previous query. Please note, you can only search about 1 to 2 weeks back in the News Feed.

Publishing

You can publish to the Facebook graph by issuing HTTP POST requests to the appropriate connection URLs, using an access token. For example, you can post a new wall post on Arjun's wall by issuing a POST request to https://graph.facebook.com/arjun/feed:
curl -F 'access_token=...' \
     -F 'message=Hello, Arjun. I like this new API.' \
     https://graph.facebook.com/arjun/feed
The Graph API reference provides more detailed information on the supported arguments and their corresponding values.
You can comment on or like any object that has a /comments or /likes connection by posting to https://graph.facebook.com/OBJECT_ID/comments and https://graph.facebook.com/OBJECT_ID/likes, respectively:
curl -F 'access_token=...' \
     https://graph.facebook.com/313449204401/likes
Most write operations require extended permissions for the active user. See the authentication guide for details on how you can request extended permissions from the user during the authentication step.
We support writing the following types of objects:
Method Description Arguments
/PROFILE_ID/feed Publish a new post on the given profile's feed/wall message, picture, link, name, caption, description, source, place, tags
/OBJECT_ID/comments Comment on the given object (if it has a /comments connection) message
/OBJECT_ID/likes Like the given object (if it has a /likes connection) none
/PROFILE_ID/notes Publish a note on the given profile message, subject
/PROFILE_ID/links Publish a link on the given profile link, message, picture, name, caption, description
/PROFILE_ID/events Create an event name, start_time, end_time
/EVENT_ID/attending RSVP "attending" to the given event none
/EVENT_ID/maybe RSVP "maybe" to the given event none
/EVENT_ID/declined RSVP "declined" to the given event none
/PROFILE_ID/albums Create an album name, message
/ALBUM_ID/photos Upload a photo to an album message, source, place (multipart/form-data)
/PROFILE_ID/checkins Create a checkin at a location represented by a Page coordinates, place, message, tags

Deleting

You can delete objects in the graph by issuing HTTP DELETE requests to the object URLs, i.e,
DELETE https://graph.facebook.com/ID?access_token=... HTTP/1.1
To support clients that do not support all HTTP methods (like JavaScript clients), you can alternatively issue a POST request to an object URL with the additional argument method=delete to override the HTTP method. For example, you can delete a comment by issuing a POST request to https://graph.facebook.com/COMMENT_ID?method=delete.
You can delete a like by issuing a DELETE request to /OBJECT_ID/likes (since likes don't have an ID).

Analytics

When you register your app, you can get detailed analytics about the demographics of your users and how users are sharing from your application with Insights.
The Graph API provides programmatic access to all of this data so you can integrate Platform data into your own, custom analytics systems.
To download Insights data, you first need to obtain an app access token.
Once you have your application access token, you can download analytics data for your application at:
https://graph.facebook.com/app_id/insights?access_token=...
That URL outputs all of the analytics data available via the API, including the total number of users, number of active users, and a number of other detailed metrics. For example, you can get the number of impressions of your app's canvas page:
https://graph.facebook.com/app_id/insights/application_canvas_views/day?access_token=...
You can use since and until to specify the time range for which you want data. Both arguments accept times in almost any valid date format:
https://graph.facebook.com/app_id/insights?access_token=...&since=yesterday
Explore the Insights product, the base /insights URL, and the Insights documentation for more information.

Batch Requests

If your app needs the ability to access significant amounts of data or make changes to several objects at once, it is more efficient to combine these operations than to make multiple HTTP requests.
To batch requests, please refer to our documentation.

Specifying Locale

If your app needs the ability to retrieve localized content in the language of a particular locale, add the locale parameter.
https://graph.facebook.com/...?access_token=...&locale=LOCALE
The locales that Facebook supports are available in an XML file. For more information on locales, check out the Internationalization documentation.

Concepts

Batch Requests
If your application needs the ability to access significant amounts of data in a single go - or you need to make changes to several objects at once, it is often more efficient batch your queries rather than make multiple individual HTTP requests. To enable this, the Graph API support Batching. Batching allows you to pass instructions for several operations in a single HTTP request.
Permissions
Permissions to access GRAPH API fields and connections.
Real-time Updates
The Graph API supports real-time updates to enable your application using Facebook to subscribe to changes in data from Facebook. Your application caches data and receives updates, rather than polling Facebook’s servers. Caching data and using this API can improve the reliability of your application and decrease its load times.

Objects

Achievement(Instance)
Instance for an achievement for a user.
Album
A photo album
Application
An application registered on Facebook Platform
Checkin
A checkin made through Facebook Places or the Graph API.
Comment
A Comment on a Graph API object
Domain
A website domain within the Graph API
Event
A Facebook event
FriendList
A Facebook friend list
Group
A Facebook group
Insights
Statistics about applications, pages, or domain.
Link
A shared link
Message
A message in a thread
Note
A Facebook Note
Offer
An Offer published by a page.
Order
An order object associated with Facebook Credits.
Page
A Facebook Page
Photo
An individual photo within an album
Post
An individual entry in a profile's feed
Question
A question asked by a user, as represented in the Graph API.
QuestionOption
An option allowed as an answer to a question.
Review
A review for an application
Status message
A status message on a user's wall
Thread
A message thread
User
A user profile.
Video
An individual video
at

No comments:

Post a Comment

Subscribe to: Post Comments (Atom)