Back to News for Developers

Graph API v2.1 and updated iOS and Android SDKs

August 7, 2014ByHarshdeep Singh

At f8 2014, we announced a new version of the Graph API v2.0. We also announced that moving forward, the primary way we'd release changes to our Platform would be through new API versions. Versioning provides a 2-year stability guarantee for Core APIs and gives you control over when you upgrade different instances of your app to use the latest platform features.

Today, we're pleased to announce the release of Graph API v2.1 as well as updated iOS and Android SDKs designed to work with this new version.

Version 2.1 incorporates several commonly requested features that build on the changes in v2.0 with the goal of increasing consistency and simplicity for developers. It's available today to all apps — and is now the default version for all new apps.

For a full list of features, please refer to the changelog and the v2.0 to v2.1 upgrade guide.

v2.1 Feature Highlights

  • Pages are able to mention other Pages in posts published via the API. If you want to publish mentions of pages other than those managed by your app's developers, you'll need to submit for review by Facebook.
  • /friends edge on the User object now provides access to total friend count. This is retroactively supported in v2.0 as well.
  • The root node of v2.1 Graph API responses will usually be a JSON object, rather than raw booleans, integers or strings. One exception is /oauth/access_token, which will return a string in case of success.
  • API v2.1 provides access to the data displayed in the new App Insights through a new 'app_insights' edge on the Application object.
  • Field expansion syntax is now more concise.
  • A new URL node makes it easier to access Open Graph and Share metadata for that URL.

Breaking Changes & Deprecations

  • FQL and the REST API are not available in v2.1. They remain available in v1.0 until April 30, 2015 and v2.0 until August 7, 2016.
  • The syntax for field expansion has become more concise in v2.1 — but the previous syntax will still be accepted. v1.0 and v2.0 have also been updated to now accept both the previous syntax and the new syntax.
  • The Login Dialog no longer accepts the legacy return_session and session_version parameters.
  • The /insights edge will be removed from the Application object in v1.0 and v2.0 on November 5, 2014 (90 days from today). You should update your apps to call /v2.1/{app_id}/app_insights instead.
  • The liked field will no longer be returned in the page property of the signed_request object for Page Tab apps created from today onwards. For apps created before today, from November 5, 2014 (90 days from today), the liked property will always return true regardless of whether or not the person has liked the page.
  • The Recommendations Bar social plugin has been deprecated. After Wednesday November 5, 2014 (90 days from today), the Recommendations Bar will no longer render on any website.

Changes to Platform Policy

In addition to the launch of API v2.1, today, we are announcing two changes to our Platform Policies. Developers should update their apps to comply with these policy changes by November 5, 2014 (90 days from today).

  • Games which include mandatory or optional in-app charges must now disclose this in their app's description, either on Facebook or other platforms it supports. This is to give people a clear indication that your game may charge people during gameplay.
  • You must not incentivize people to use social plugins or to like a Page. This includes offering rewards, or gating apps or app content based on whether or not a person has liked a Page. It remains acceptable to incentivize people to login to your app, checkin at a place or enter a promotion on your app's Page. To ensure quality connections and help businesses reach the people who matter to them, we want people to like Pages because they want to connect and hear from the business, not because of artificial incentives. We believe this update will benefit people and advertisers alike.

How to Upgrade to v2.1

To upgrade to v2.1, mobile developers should download our latest iOS and Android SDKs. Web developers should declare v2.1 in the version property when calling the init() method of the JavaScript SDK and specify v2.1 in your URLs when calling the Graph API.

In line with our 2-year stability guarantee, v2.0 will be deprecated on August 7, 2016. After that date, all apps will automatically be upgraded to v2.1. As announced at f8 2014, v1.0 will be deprecated on April 30, 2015.

With each API version living for at least two years, we're excited to enhance stability, simplicity and consistency across the Graph API. We'll continue to focus on this in future versions.