Facebook’s Platform supports both versioning and migrations so that app builders can roll out changes over time. In order to provide versioning and stability, we have divided full range of Platform services and features into two groups: core and extended.
Why do we have versions?
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 your app on their phone may take a long time to upgrade (or may never upgrade).
As mentioned, each version will remain for at least 2 years from release, therefore giving you a solid timeline for how long your app will remain working, and for how long you have to update it to newer versions.
Core and Extended
In order to provide versions, Platform components – APIs and SDKs – are divided into those that are labelled ‘core’ and those that are labelled ‘extended’.
Core APIs and SDKs are central to the Facebook Platform offered to developers. 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 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.
Versioning
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 APIs. Multiple versions of APIs or SDKs can exist at the same time with different functionality in each version.
The latest Graph API version is v3.0.
Version Schedules
Each version is guaranteed to operate for at least two years. A version will no longer be usable two years after the date that the subsequent version is released.
So if API version v2.3 is released on March 25th, 2015 and API version v2.4 is released August 7th, 2015 then v2.3 would expire on August 7th, 2017, two years after the release of v2.4.
For APIs, once a version is no longer usable, any calls made to it will be defaulted to the next oldest usable version. Here’s a timeline example:
For SDKs, a version will always remain available as it is a downloadable package, however beyond its 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.
You can find specific info about version timelines, changes, and release dates on changelog page.
Facebook does reserve the right to make changes in any API in a short period of time for issues related to security or privacy. These changes don’t happen often, but they do happen.
If you don’t specify a version for an API, rhen it is an unversioned call. An unversioned call will default to the oldest available version of the API.
An unversioned call will always point to the oldest version still available. Because of this, recommendation is to always specify versions when making calls, where possible.
When using the JavaScript SDK for Facebook you can’t make unversioned API calls.
An app can make calls to the version of the API that was the latest available when the app was created, as well as any newer, un-deprecated versions launched after the app is created.
As an example, if your app was created after v2.0 was released, it will be able to make calls to v2.0 until the expiration date of that version, and any subsequent versions (v2.1 etc) until their expiration dates.
If an app is created and isn’t used to make any calls or requests before a new version is released, it will not have the ability to use older versions. Here’s an example to explain this:
- If your app was created while v2.0 was the latest version available, but not used until after v2.1 had launched, it will only be to use v2.1, and not v2.0.
- If your app was created while v2.0 was the latest version available, and then used before v2.1 had launched, it will still be able to use v2.0 even after the launch of v2.1.
Making Versioned Requests
Graph API – Whether core or extended, almost all Graph API endpoints are available through a versioned path.
Dialogs – Versioned paths aren’t just true for API endpoints, they’re also true for dialogs and social plugins. For example, if you want to generate the Facebook Login dialog for a web app, you can prepend a version number to the endpoint that generates the dialog:
client_id={app-id}
&redirect_uri={redirect-uri}
Social Plugins – If you’re using the HTML5 or xfbml versions of our social plugins, the version rendered will be determined by the version specified when you’re initialising the JavaScript SDK.
If you’re inserting an iframe or plain link version of one of our plugins, you’d prepend the version number to the source path of the plugin:
<iframe
src=”//www.facebook.com/v3.0/plugins/like.php?href=https%3A%2F%2Fdevelopers.facebook.com%2Fdocs%2Fplugins%2F&width&layout=standard&action=like&show_faces=true&share=true&height=80&appId=634262946633418″
scrolling=”no”
frameborder=”0″
style=”border:none; overflow:hidden; height:80px;”
allowTransparency=”true”>
</iframe>
Versioned Requests from SDKs
If you’re using the Facebook SDK for iOS, Android or JavaScript, making versioning calls is largely automatic. Note that this is distinct from each SDKs own versioning system.
For JavaScript – The JavaScript SDK can only use different API versions if you’re using the sdk.js path. If you’re using FB.init() from the JavaScript SDK, you need to use the version parameter, like this:
FB.init({
appId : ‘{app-id}’,
version : ‘v3.0’
});
If you set the version flag in the init, then any calls to FB.api() will automatically have the version prepended to the path that’s called. The same is true for any dialogs for Facebook Login that happen to get called. You will get the Facebook Login dialog for that version of the API.
If you need to, you can override a version by just prepending the version to the path of the endpoint in the FB.api() call.
For iOS – Each version of the iOS SDK that’s released is tied to the version that’s available on the date of release. This means that if you’re upgrading to a new SDK you’re also upgrading to the latest API version as well (although you can manually specify any earlier, available API version with [FBSDKGraphRequest initWithGraphPath]). The API version is listed with the release of each version of the iOS SDK.
Much like the JavaScript SDK, the version is prepended to any calls you make to the graph API through the iOS SDK. For example, if v2.7 was the most recent version of the API, the call /me/friends – used in the following code sample – will actually call /v2.7/me/friends:
[[[FBSDKGraphRequest alloc] initWithGraphPath:@”me/friends”parameters:@{@”fields”: @”cover,name,start_time”}]
startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
(…)
}];
You can override the version of the call with [FBSDKGraphRequestConnection overrideVersionPartWith].
For Android – Each version of the Android SDK that’s released is tied to the version that’s available on the date of release. This means that if you’re upgrading to a new SDK you’re also upgrading to the latest API version as well (although you can manually specify any earlier, available API version with GraphRequest.setVersion()). The API version is listed with the release of each version of the Android SDK.
Much like the JavaScript SDK, the version is prepended to any calls you make to the graph API through the Android SDK. For example, if v2.7 was the most recent version of the API, the call /me – used in the following code sample – will actually call /v2.7/me:
GraphRequest request = GraphRequest.newGraphPathRequest (
accessToken,
“/me/friends”,
new GraphRequest.GraphJSONObjectCallback() {
@Override
public void onCompleted(
JSONObject object,
GraphResponse response) {
// Application code
}
});
Bundle parameters = new Bundle();
parameters.putString(“fields”, “id,name,link”);
request.setParameters(parameters);
request.executeAsync();
You can override the version of the call with GraphRequest.setVersion().
API Veriosn Upgrade Tool
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.
Test Users – 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.
Upgrading Early – 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
- Upgrading Developers and Admins – 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.
- Upgrading All Calls – 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.
