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 our APIs. Multiple versions of APIs or SDKs can exist at the same time with different functionality in each version.
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.
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 2.3 is released on March 25th, 2015 and API version 2.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 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.
You can find specific info about our version timelines, changes, and release dates on our changelog page.
Will everything core remain completely unchanged in a version?
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.
What happens if I don't specify a version for an API?
We refer to this as an unversioned call. An unversioned call will default to the oldest available version of the API. Consider this hypothetical life cycle of API versions:
An unversioned call will always point to the oldest version still available at the top of the chart. This is currently v2.0, but after two years it'll be v2.1, then v2.2, etc.
Because of this, our recommendation is to always specify versions when making calls, where possible.
Can my app make calls to versions older than the current version?
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.
Marketing API Versioning
The Marketing API has its own versioning scheme. Both version numbers and their schedules are different from the Graph API's state of things.
Learn more about Marketing API VersioningMaking Versioned Requests
Graph API
Whether core or extended, almost all Graph API endpoints are available through a versioned path. We've afull guide to using versions with the Graph API in our Graph API quickstart guide.
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:
https://www.facebook.com/v2.1/dialog/oauth? 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:
<iframesrc="//www.facebook.com/v2.1/plugins/like.php?href=https%3A%2F%2Fdevelopers.facebook.com%2Fdocs%2Fplugins%2F&amp;width&amp;layout=standard&amp;action=like&amp;show_faces=true&amp;share=true&amp;height=80&amp;appId=634262946633418"scrolling="no"frameborder="0"style="border:none; overflow:hidden; height:80px;"allowTransparency="true"></iframe>
Making 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.
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 :'v2.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 theFB.api() call.
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 though the iOS SDK. For example, if v2.2 was the most recent version of the API, this call will actually call /v2.2/me:
[[[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].
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 withRequest.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 though the Android SDK. For example, if v2.2 was the most recent version of the API, this call will actually call /v2.2/me:
Request request =newRequest(session,"me/events?fields=cover,name,start_time"); request.executeAsync();
You can override the version of the call with Request.setVersion().
Migrations
Migrations are changes to the extended elements of Facebook Platform which can introduce new behaviors, and therefore breaking changes.
Migrations that are currently still in progress are listed on our Platform roadmap. Migrations have at least a 90-day window during which you must migrate your app. Once a window begins, the post-migration behavior will become the default for new apps. Then, when the migration window is completed, the pre-migration behavior will no longer be available at all.
You can find info about completed migrations in a separate section of our roadmap.
Managing Migrations via Graph API
Migrations can be managed via the migrations field in the /app node:
You can make an update call on the edge to activate and deactivate migrations.
Managing Migrations via App Dashboard
You can activate and deactivate available migrations in the App Dashboard under Settings > Migrations:
Temporary Client-side Activation of Migrations
Instead of activating the migration in your App dashboard, or via the API, it's possible to instead add a special flag to your API calls that sets the migration. The flag is called migrations_override and requires you to specify a JSON blob that describes what migrations you want to turn on or off. For example, if you were making a raw call you could pass:
http://graph.facebook.com/path? migrations_override={"migration1":true,"migration2":false}
Using this, you can call the new API through client updates instead of having to get all callers to update to calling the new API at the same time. It's also very useful for debugging.
The names for these migrations are found on the /app node mentioned above.