Facebook's Platform has a core and extended versioning model, since Oct 30th, 2014. With Marketing API versioning, all breaking changes will be in a new version. Multiple versions of Marketing APIs or Ads SDKs can exist at the same time with different functionality in each version.
Developers should understand in advance when a Marketing API or Ads SDK will change. While you have a 90-day window to adopt changes, how and when to move to the new version is your choice.
When a new version of the Marketing API releases, we continue to support the previous version of the Marketing API for at least 90-days. You have at least 90 days to move over to the new version. During the 90-day deprecation period, you can call both the current version and the deprecated version, and you have a 90-day period to move to the new version. After the 90 day period ends, the deprecated version stops working. Once a version is unavailable, any calls made to that version number will FAIL.
For example, Marketing API version 2.2 released on October 30th, 2014 and Marketing API version 2.1 expired on January 28th, 2015, 90 days after the release of v2.2. It actually expired later than that date, on March 11th, 2015.
Here is a sample timeline. Note that we may not always release a new version at the end of the 90 days of the previous version's deprecation. In the example, v2.0 is deprecated some time before v2.2 is released:
For SDKs, a version always remains available as it is a downloadable package, however beyond its end-of-life date, it may rely upon Marketing APIs or methods which no longer work, so you should assume an end-of-life SDK is no longer functional.
We refer to this as an unversioned call. Unversioned calls are invalid and will fail when made against Marketing API endpoints.
You can call the version of the Marketing API that was the latest available when the app was created, as long as it has not been deprecated. It can also make calls to any newer, un-deprecated versions launched after the app is created.
For example:
If an app was not used - to make any Marketing API calls or requests - after being created, it will not have the ability to use those versions if any newer version is launched. Here's another example to explain this:
There are a few differences between how Marketing API and the rest of Graph API. For the details on Platform API versioning, see Graph API, Versioning.
Use Graph API v2.0 by default
in App Dashboard before April 30th, 2015, or as enforced after that date.All Marketing API endpoints are available through a versioned path. Pre-pend the version to the start of the request path. For example:
curl -G \ -d "access_token=<ACCESS_TOKEN>" \ "https://graph.facebook.com/v2.2/me/adaccounts"
This works for all versions, in this general form:
https://graph.facebook.com/v{n}/{request-path}
where n
is the version needed. See a full list of available versions in our Changelog. All of our Marketing API Reference provide per-version information.
With migrations, you set migration on or off in App Dashboard, as described below. With versioning, we are making Marketing API functionality more transparent by moving the setting into the endpoint:
https://graph.facebook.com/v{n}/{request-path}
You can know what behavior to expect out without having to manually visit your app's migration panel.
Migrations are only for special scenarios where changes need to be made that cannot go into versioning. Typically this is if the underlying data model has changed. Migrations apply across all versions.
Migrations that are currently still in progress are listed on our migrations page. 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.
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.
You can activate and deactivate available migrations in the App Dashboard under Settings > Migrations
. Please note, that the list of migrations may not be the same as in the image below, as the available migrations are different for different apps, at different time. And if you see a migration Use Graph API v2.0 by default
, it is for Graph API only, not Marketing API.
Instead of activating the migration in your App Dashboard, or via the Marketing API, it's possible to instead add a special flag to your Marketing 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 Marketing API through client updates instead of having to get all callers to update to calling the new Marketing 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.