Facebook Announces More Stable Platform with Versioning and Graph API 2.0

Thursday, May 1, 2014

During the f8 developer conference Facebook assured app developers that providing a better mobile experience for both developers and users is a priority.

Among the announcements was API Versioning and a two-year stability guarantee for core products such as Login, Sharing, Requests, SDKs and frequently used Graph API endpoints. This means that if Facebook makes any changes to these products, they will guarantee to continue to support the previous version for at least two years. Versioning also gives control over how developers upgrade different instances of an app to use the latest platform features.

New elements of Graph API 2.0 include:

App-scoped user IDs: To better protect people's information, Facebook will begin to issue app-scoped user IDs instead of original user IDs for people who first login to an app using Graph API 2.0. People who have already logged into an app will still retain their original user ID. For developers operating multiple apps, the Business Mapping API provides the ability to map the same person's ID between them.

Test Apps: Provides a way to create and manage apps for use in testing, development and staging, test apps also serve as a central place to manage people's roles across all of a developer’s apps.

Social Context API: A simple way to surface a person's friends' activity alongside content.

Tagged Places API: An easy way to build experiences using the places where a person has been tagged.

Tagging and Inviting APIs: New APIs to help build interfaces for tagging friends in stories and inviting friends to use an app.

Removing Rarely Used API Endpoints. Facebook is removing several rarely used API endpoints which are outlined in the changelog.

Facebook's Platform supports both versioning and migrations so that app builders can roll out changes over time. Platform components, APIs and SDKs, are divided into those that are labeled 'core' and those that are labeled 'extended'.

Core APIs and SDKs are central to the Facebook Platform. These elements are subject to a version system, and guarantee that anything considered a core API node, field, edge, dialog, SDK or SDK method will remain available and unchanged for at least two years from the launch of that version. Any changes that would break anything in core must do so only by releasing a new version.

Core elements include:

- Facebook Login dialog

- Share dialog

- Requests dialog

- The Like button

- The Facebook SDK for iOS

- The Facebook SDK for Android

- Some methods of the Facebook SDK for JavaScript

- Some Graph API fields and endpoints

Extended is everything beyond that, APIs and SDKs that are subject to more rapid change. These SDKs and APIs are still accessed through different versions, but they can potentially be modified or removed at any time, subject to 90-day migrations that would be announced on the platform roadmap. Alternatively they may simply be included with the next available API version, however they will not be included under the 2-year window for that version, and may change long before it expires.

Not all APIs and SDKs share the same versioning system. For example, the Graph API is versioned with a different pace and numbering compared to the iOS SDK. All SDKs released after 30th April 2014 support the ability to interact with different versions of our APIs. Multiple versions of APIs or SDKs can exist at the same time with different functionality in each version.

The goal for having versioning is for developers building apps to be able to understand in advance when an API or SDK might change. They help with web development, but are critical with mobile development because a person using an app on their phone may take a long time to upgrade (or may never upgrade).

Each version is guaranteed to operate for two years (except for API version 1.0, which has an expiration date one year after its release date), but what specifically happens is this: A version will no longer be usable two years after the date that the subsequent version is released. So if API version 2.0 is released on April 30th, 2014 and API version 2.1 is released May 30th, 2014 then v2.0 would expire on May 30th, 2016, two years after the release of v2.1.

For APIs, once a version is no longer usable, any calls made to it will be defaulted to the next oldest usable version. For SDKs, a version will always remain available as it is a downloadable package, however beyond it's end-of-life date, it may rely upon APIs or methods which no longer work, so you should assume an end-of-life SDK is no longer functional.