This guide helps you upgrade your apps across versions. It lists the steps you should take to test and prepare your app for a version upgrade. For changes in each platform release see our platform changelog.
We recommend upgrading multiple versions at a time. Upgrading to the latest available version maximizes the time between upgrades.
The API Upgrade Tool displays a customized list of changes that impact an app when upgrading to a specified target version. This is particularly useful when upgrading multiple versions since it displays all relevant changes between the source and target versions.
You can test how a production app would behave in a certain version by using Test Users. You can edit a test user to override the minimum Graph API Version applied for calls using that user's access token. This way, you can verify upgraded behavior for the existing production version of your app.
A month before a Version Upgrade, an API Version Upgrades section will be added to the Advanced Settings section of the App Dashboard for affected apps. This section has the following functions:
This upgrades all developers and admins of an app to the next available version. This is similar to overriding the version with a test users, with the advantage of the richer and more varied data that comes from testing with real people.
This upgrades all calls made by an app to the next available version. We recommend using this after testing the upgraded behavior with either test users or app developers first. Upgrading early is useful since it preserves the option of going back to the original version in case of unforeseen bugs or issues.
GET {user_id}/accounts
Now require either manage_pages
or pages_show_list
permission in v2.5.
POST {page_id}/call_to_actions
and POST/DELETE {call-to-action-id}
require the new permission pages_manage_cta
that we introduce in v2.5.
We now automatically disable RTU subscriptions if the callback URL fails for 7 days straight. You can reenable it with a POST
request to /subscriptions
. This change does not apply to payments subscriptions.
We now have consistent naming for three-level campaign structure between API and UI. This changes naming at endpoint, params, fields, and enum level. For the full list of changes, refer here.
In the past, responses from Graph API calls returned a set of default fields. In order to reduce payload size and improve latency on mobile networks we have reduced the number of default fields returned for most Graph API calls. In v2.4 you will need to declaratively list the response fields for your calls.
If your app references the {id}/links or {id}/statuses for Users or Pages, you will need to modify these calls to use {id}/feed.
When making a call to a Page and retrieving data, v2.4 imposes a maximum limit of 100 results. This will impact the /feed
, /posts
, and /promotable_posts
edges on Pages. If you expect your Graph API call to exceed this limit you will need to page through the results.
There are a number of Page permissions changes between v2.3 and v2.4 that your apps will need to account for. Notably, a Page access token is now required to interface with /v2.4/{page_id}/promotable_posts
, /v2.4/{page_id}/offers
, and /v2.4/{page_id}/milestones
. Additionally, Page Milestones and Offers now require manage_pages
and publish_pages
permissions.
In Graph API v2.4 we've removed GET
operations on {event_id}/invited
, {event_id}/likes
, and {event_id}/sharedposts
.
There are a handful of features and permission deprecations that are set to 90 day and 2 year schedules. See Platform v2.4 Changelog, 90 Day Deprecations for more details.
In the past, Real-Time Updates (RTUs) from Pages only contained the ID of the object that triggered the update. This required you to make an additional call to Graph API to discover more context about the update using the {object_id}
. As of March 25, 2015 Page RTUs include the actual content based on the object type which eliminates the need for an additional call.
We also added a new RTU
property for Ratings on Pages. Developers can now subscribe to this property to get an update each time a Rating update occurs.
If you make a call to an edge without providing a limit parameter, v2.3 imposes a default limit of 25 results. If you expect your Graph API call to exceed this limit, include the limit
parameter for a larger response count.
In v2.3 all Graph API responses now serialize empty arrays in valid JSON format. If your code relies on the old way of handling empty arrays see the changelog entry for more details Facebook Platform Changelog, API version 2.3.
If you build your own Login flow, there is an update to the OAuth code exchange that now conforms to the latest OAuth RFC spec. See details in the changelog entry, see Facebook Platform Changelog, API version 2.3.
We changed the behavior of picture edges on Nodes that don't support the picture edge. Prior to Graph API v2.3 this edge returned an question mark image representing an undefined picture.
For this edge on Link
, Post
, Thread
, Comment
, and Status
nodes the Graph API now returns an error.
Previous versions of Graph API supported all app types that made calls to/v2.x/{user-id}/apprequests
. The intended use for this edge is for invite requests for Game apps. Starting with v2.3, if your app makes use of the Requests
object but is not a game you should modify your app to use App Invites.
Page Access Tokens Required - If your app performs operations on behalf of a Page, such as posts, comments, and likes, these are now made in the context of the passed access token. If you make actions on behalf of a Page, check that your code passes the respective Page access token.
country
Renamed countries
- We renamed the feed_targeting
field's country
subfield on a Page post to countries
. This impacts calls to POST|GET /v2.3/{page-post-id}
.
Deleting Pages - If your app deletes Page posts with DELETE /v2.3/{comment-id}
you now need to pass a Page access token with admin permissions of the page.
country
Requirement - If your app updates the location
field of a /v2.3/{page-id}
you must include a country
sub-parameter. If your country='United States'
you also need to include a state
sub-parameter.
POST
Changes for Page Fields - POST
updates on the Page
fields hours
, parking
, or payment_options
now behave differently. See Facebook Platform Changelog, API version 2.3.
user_posts
- We added a new permission user_posts
that enables apps to access posts on a person's timeline. Previously you could access this content through the read_stream
permission. If your app had read_stream
permission it has been automatically granted the user_posts
permission. See Facebook Platform Changelog, API version 2.3.
Publishing Posts for Pages - If your app publishes posts for a Page you now need both the publish_pages
and manage_pages
permissions. If a user had granted the publish_actions
and manage_pages
permissions in v2.2 or below, we have automatically granted that user publish_pages
. However, to use publish_pages
or to request it from new users in v2.3 and up, you must have been approved to use that permission via Login Review.
read_friendlists
Renamed - We renamd the read_friendlists
permission to read_custom_friendlists
. See Facebook Platform Changelog, API version 2.3. You'll need to specify read_custom_friendlists
in the Login Dialog from v2.3 onwards. For people who granted read_friendlists
in previous versions, this will be returned as read_custom_friendlists
when calling /me/permissions
in v2.3 and up.
Consistent place
Field - If your app uses Place
tags in Photos
, Albums
, Videos
, and Statuses
you need to make a few changes to migrate to Graph API v2.3. In v2.3 so the place
field always contains consistent data including the name
field and a location
object.
Event
and place
- We updated the Event
node to store Place data more consistently. Before an event's location
field contained the name
of the place, and the venue
field contained the location
object. In v2.3 both location
and venue
fields are deprecated; we store the name
and location
object in the place
field.
There are a numbers of features and Social Plugins that are deprecated in 90 days. See Platform v2.3 Changelog, 90 Day Deprecations.
Comments Plugin Changes - If you use the Facebook Comments Plugin, upgrade your Facebook JS SDK url to pass the version parameter version=v2.3
. After June 22, 2015, we will automatically upgrade older versions of the Comments Plugin to v2.3.
Facebook Like Box - If you use the Facebook Like Box, we recommend you use the Page Plugin instead. To do this, replace the div class
of your Facebook Like Box div=fb-like-box
with div=fb-page
and it upgrades automatically.
Many apps get real time updates for changes to pages. These include comments, posts and other data. In versions previous to v2.2, this was done by adding an app to the /{page-id}/tabs
app that wasn't registered as a page tab app.
We're deprecating using the tabs
edge to register your app for real time updates. Instead of using the tabs
edge, you can use the new /v2.2/{page-id}/subscribed_apps
endpoint to manage subscriptions to real time updates.
All apps are now required to use the new real-time updates interfaces.
In previous versions it was possible to use a User Access Token to access some page data through some interfaces. In v2.2, many interfaces now require use of a Page Access Token. Please see the various entries listed in the changelog for details.
ids=x,y,z
SyntaxIf you're using the ids=
syntax, covered in our Using the Graph API doc, you are now limited to requesting only 50 IDs at a time.
/{page_id}/admins
Edge is Now /{page_id}/roles
In addition to moving the interface to a new edge name, the values returned are different. Please see the changelog for more details.
/{page_id}/settings
Uses a New Format For UpdatesPrevious versions used the setting
and value
params. In v2.2, you should specify the option
param which should be an object containing a single key/value pair with the setting enum as the key. Please see the settings
edge for details.
/{group-id}/albums
Now Uses the Same Syntax as /{user_id}/albums
Previous versions of the albums
edge on groups had a different format than the edge on users. They now use the same format. Please see the /{user-id}/albums
edge for more information.
Several other rarely used features are being deprecated in 90 days. Please see that section of the changelog for more information.
If you have any questions, please check out the FAQs.