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}/accountsNow 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}/rolesIn 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}/albumsPrevious 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.
