Skip to content

Instantly share code, notes, and snippets.

@manchunlam

manchunlam/upgrade.md

Last active August 29, 2015 14:14
Show Gist options
  • Save manchunlam/90a44b7c157123ec33df to your computer and use it in GitHub Desktop.
Save manchunlam/90a44b7c157123ec33df to your computer and use it in GitHub Desktop.
Download ZIP
Graph API Upgrade
Raw
upgrade.md

Graph API Version Upgrade

Table of Contents

  1. [Facebook App and Graph API Versioning] (#i-facebook-app-and-graph-api-versioning)
  2. [Graph (Platform) API Changelog v1.0 to v2.0] (#ii-graph-platform-api-changelog-v1-0-to-v2-0)
    1. App-Scoped User ID
    2. [New Permission to Get a User's Friends] (#b-new-permission-to-get-a-users-friends)
    3. /me/friends has New Meaning
    4. Facebook App Cannot See User’s Friends’ Data
    5. Friend List No Longer Contains Individual Members
    6. Default Permissions have a Name Change
    7. Facebook will Review Your App if Too Many Permissions are Asked
    8. Deprecate /me/locations Endpoint
    9. All Endpoints Require access_token
    10. Added, and Deprecated Permissions and Endpoints
  3. Graph (Platform) API Changelog v2.0 to v2.1
    1. REST API Deprecated
    2. FQL Deprecated
    3. App Insights Endpoint Changed
    4. Nested API Request for Parent and Children Entities
    5. Open Graph Object Query
    6. All Endpoints Return Valid JSON
    7. Permission installed Removed
    8. Field-Name Change for User Profile Picture
    9. /{post-id} Includes All Photos
  4. Platform API Changelog v2.1 to v2.2
    1. Subscribe a Facebook App to a Facebook Page's Updates
    2. Must Use Page Access Token for Page Data Retrieval
    3. /{page-id}/roles Replaces /{page-id}/admins
    4. Request Body Changed for Updating Page Settings
    5. Same Reponse from /{group-id}/albums and /{user-id}/albums

I. Facebook App and Graph API Versioning

Summary

An un-versioned API call will called the oldest version that your Facebook App migrated to.

Situation

Facebook App "Foobar" will be forced to migrate to v2.0 on May 1st, 2015. Therefore, on that day forward, any un-versioned call is, behind the scenes

/me?fields=name

is exactly the same as

/v2.0/me?fields=name

Documentation

When a version of the API expires, apps that still use the expired version will automatically start using the oldest supported version of the API.

This means that if your app is using v1.0 calls on May 1st, 2015, calls will return behavior from v2.0 of the API. This is true even if we've released newer versions of the API.

II. Graph (Platform) API Changelog v1.0 to v2.0

Endpoints like /me, /{post-id}, /{app-id}, etc

A. App-Scoped User ID

There is a caveat to the following notes, please read it at the end of each bullet point.

  1. Each application will return a different user.id for the same Facebook profile.

    # With the same Facebook user

# Using access_token from Facebook App "Foo"
/me?fields=id

# => { id: 12345 }

# Using access_token from Facebook App "Hello World"

/me?fields=id

# => { id: 17 }

    Caveat

    For all Facebook user who already authorized an Facebook App, the user.id will stay constant (i.e. same as the v1.0 user.id)

  2. Mapping user.id across Facebook Apps

    You can only do this if all your Facebook Apps are under the same business.

    Use Business Manager to group all those Facebook Apps under the same business. And then use the [Business Mapping API] (https://developers.facebook.com/docs/apps/for-business).

B. New Permission to Get a User's Friends

The new permission is user_friends.

This permission is default in v1.0; it must now be asked for separately in v2.0.

C. /me/friends has New Meaning

v2.0 will return only friends of that user who have authorized your app.

v1.0 will return all friends.

D. Facebook App Cannot See User's Friends' Data

All friends_* permissions are removed.

In v1.0, an App can see data of its users' friends. In v2.0, that is no longer possible.

Caveat

If your friend has authorized the same app as you did, that app can get your friend's data by querying directly against your friend. Not through you (and your authorization).

E. Friend List No Longer Contains Individual Members

The /{user-id}/friendlists will return responses like

[{ id: '123', name: 'Close Friends', list_type: 'close_friends' }]

[Documentation] (https://developers.facebook.com/docs/graph-api/reference/v2.2/friendlist/)

Individual members of the friend-list will not be returned.

F. Default Permissions have a Name Change

In v1.0, the permission is basic_info.

In v2.0, the same permission is renamed to public_profile.

The capabilities are the same.

G. Facebook will Review Your App if Too Many Permissions are Asked

The following are the maximum permissions to ask for without Facebook's review

  1. public_profile
  2. email
  3. user_friends

Apps created before April 30th, 2014 must be reviewed by April 30th, 2015. Unapproved permissions will not be shown in login dialog afterwards.

Other Apps, no deadline for review. However, they must be reviewed before prompting for additional permissions.

H. Deprecate /me/locations Endpoint

The new endpoint in v2.0 is /me/tagged_places. An App needs user_tagged_places permission to use it.

I. All Endpoints Require access_token

A Facebook App can't call any endpoints, unless a user has authorized it at least once.

J. Added, and Deprecated Permissions and Endpoints

  1. Permissions

    • Removed

      create_event
manage_friendlists
read_requests
user_checkins
user_notes
user_online_presence
user_questions
user_subscriptions
xmpp_login
friends_about_me
friends_actions.books
friends_actions.fitness
friends_actions.music
friends_actions.news
friends_actions.video
friends_actions:APP_NAMESPACE
friends_activities
friends_birthday
friends_checkins
friends_education_history
friends_events
friends_games_activity
friends_groups
friends_hometown
friends_interests
friends_likes
friends_location
friends_notes
friends_online_presence
friends_photos
friends_questions
friends_relationships
friends_relationship_details
friends_religion_politics
friends_status
friends_subscriptions
friends_videos
friends_website
friends_work_history

  2. Endpoints

III. Graph (Platform) API v2.0 to v2.1

A. REST API Deprecated

The REST API is complete gone.

B. FQL Deprecated

No more FQL queries

C. App Insights Endpoint Changed

In v1.0, the endpoint is /{app-id}/insights

In v2.1, the endpoint is /{app-id}/app_insights

D. Nested API Request for Parent and Children Entities

We can query parent and its children in one request

Example

Let's say I have to find

  1. My posts
  2. My Albums
  3. Photos in each of my albums
  4. Two Tags in each of my photos

And the relation among them look like this

<img src='http://g.gravizo.com/g? @startuml; skinparam classAttributeIconSize 0;

class Me {; };

class Album {;

  • name; };

class Post {; };

class Photo {;

  • name;
  • picture; };

class Tag {; };

Me "1" o-- "0..N" Album; Me "1" o-- "0..N" Post; Album "1" o--> "1..N" Photo; Photo "1" o--> "0..N" Tag; @enduml '>

Instead of making 4 calls, and for-loops, we do it like

/me?
  fields=
    albums{name, # album's name
      photos{name, # each photo's name
        picture, # each photo's URL
        tags.limit(2) # give me 2 tags per photo
      }
    },
    posts # give all my post-objects

The curl call

GET https://graph.facebook.com/me?fields=albums{name, photos{name, picture, tags.limit(2)}},posts&access_token=0a123b

E. Open Graph Object Query

To query an Open Graph Object (or App Links), do

graph.facebook.com/?id=<urlEncodedURL>

F. All Endpoints Return Valid JSON

No more raw "true" or "378293782" Sting response

It will be something like

{ "success": true }

// or

{ "id": 378293782 }

G. Permission installed Removed

A Facebook App querying /me/permissions will no longer return installed permission.

If /me/permissions returns any data (except an error), that user has installed the Facebook App.

H. Field-Name Change for User Profile Picture

/{user-id}/picture?redirect=false now uses the attribute url in the javascript response. Not uri.

redirect=true will give you the picture itself, binary response.

{ url: 'http://facebook.com/foobar.png' }

I. /{post-id} Includes All Photos

GET /{post-id}

{
  attachements: [
    { id: '123', url: 'http://facebook.com/foo.png' },
    { id: '2', url: 'http://facebook.com/hello.png' }
  ]
}

IV. Platfrom API Changelog v2.1 to v2.2

A. Subscribe a Facebook App to a Facebook Page's Updates

If your Facebook App is already a page-tab App, then your App automatically gets updates from the parent Page.

If not, you can subscribe a Facebook App to a Page.

Issue the following with a Page Access Token

POST

/{page-id}/subscribed_apps

{
  access_token: '0a1b2c'
}

The endpoint will extract the app_id from the access_token, and make that App listen to the Page for updates.

B. Must Use Page Access Token for Page Data Retrieval

A Facebook user can no longer use a User Access Token to get Page data.

A Page Access Token requires a user to ask for the manage_pages permission from the Page.

C. /{page-id}/roles Replaces /{page-id}/admins

The new endpoint will have

{
  perms: [
    "ADMINISTER", "EDIT_PROFILE", "CREATE_CONTENT", "MODERATE_CONTENT",
    "CREATE_ADS", "BASIC_ADMIN"
  ],
  roles: "Admin"
}

roles: enum{Admin, Editor, Moderator, Advertiser, Analyst}

D. Request Body Changed for Updating Page Settings

New request body will be like

POST /{page-id}/settings

{
  options: { "APPEARS_IN_RELATED_PAGES": false }
}

You can only update one setting per POST.

E. Same Response from /{group-id}/albums and /{user-id}/albums

/{group-id}/albums will use the same response format as that of /{user-id}/albums

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment