Facebook Graph API and access tokens

Posted on by

The Facebook Graph API enables you to read and write objects and connections (relationships)  in The Facebook social graph.

There are 14 graph objects available :

  1. user
  2. page
  3. group
  4. application
  5. post
  6. status message
  7. note
  8. event
  9. link
  10. checkin
  11. album
  12. photo
  13. video
  14. subscription

Each object has a collection of properties. The numer of properties is ranging from 4 (min) for the “status message” object to 23 (max) for the ” user” object.

Besides the listed objects, which can be connected to other objects, the following additional connections are defined :

  1. comments
  2. feed
  3. picture
  4. tagged
  5. statuses
  6. insights
  7. maybe
  8. invited
  9. attending
  10. declined
  11. members
  12. likes
  13. source
  14. home
  15. friends
  16. activities
  17. interests
  18. music
  19. books
  20. movies
  21. television
  22. inbox
  23. outbox
  24. updates
  25. accounts

Each object has an individual ID (xxxxxxx) and can be accessed with the URL :

http://graph.facebook.com/xxxxxx

A field query parameter can be used to filter the returned data, for instance :

http://graph.facebook.com/xxxxxx?fields=id,name, picture

Alternatively, the ID can be a name, if defined. The connections, if available, are returned in the same request if the parameter “metadata=1” is added to the request (Introspection). Multiple objects can be fetched in the same request by adding the “?ids=” parameter. A special identifier  “me” refers to the current user.

To fetch a specific connection, for instance who is attending the event zzzzzz, the URL is structured as follows :

http://graph.facebook.com/zzzzzz/attending

All responses are JSON (Javascript Object Notation) objects, a lightweight data-interchange format.

If an object is private, you will receive only the public part of the data or the following error message :

{
   "error": {
      "type": "OAuthAccessTokenException",
      "message": "An access token is required to request this resource."
   }
}

To access a graph object with an active access token (yyyyyy), the following method is used :

https://graph.facebook.com/xxxxxx?access_token=yyyyyy

All calls with access tokens are required to go over HTTPS.

An access token is granted by the concerned user, by the page or by the application. Access tokens are based on OAuth 2.0, an open protocol providing specific authorization flows for web applications, desktop applications, mobile phones, and living room devices.

In an initial launch, Facebook supports three ways of getting an access token :

  • The default authorization flow is the web server flow for use by server-side developers. The whole flow works by redirecting the user to the authorization server (Facebook) and back to the developer site.  A “Connect URL” with the domain and path of the site must be preregistered.
  • The second method is the user-agent flow in a Javascript based application. Because the code actually runs on the client device, it can’t really rely on embedded secret keys for security – in JavaScript, anyone can look at the source code and trivially extract the secret. The access token is just returned directly in the redirect response instead of requiring an extra server call with specific care for handling security issues.
  • The third method, client credentials flow, is the simplest flow – just exchange your client_id and secret for an access token, no user is involved. It’s mainly supported for accessing application-only resources.