Marketing API - Versioning

Facebook's Marketing API now supports both versioning and migrations so that app builders can roll out changes over time. Read on to understand how you are affected by versions, how to use those versions in our Marketing APIs and Ads SDKs, and what migration windows are.

Overview

While Facebook's Platform has a core and extended versioning model, starting Oct 30th, 2014, Facebook's Marketing API will move to a versioning scheme to manage changes in the Marketing API. With Marketing API versioning, all breaking changes will be rolled up into a new version. Multiple versions of Marketing APIs or Ads SDKs can exist at the same time with different functionality in each version.

The goal for having versioning is for developers building tools to be able to understand in advance when an Marketing API or Ads SDK might change. While you still have the same 90-day window to adopt changes, the control of how and when to move to the new version lies with you.

Version Schedules

When a new version of the Marketing API is launched, we'll continue to support the previous version of the Marketing API for at least 90-days, giving developers at least 90 days to move over to the new version. During the 90-day deprecation period, both versions of the API will be callable (the current version and the deprecated version), and developers have this 90-day period to move to the new version. After the 90 day period ends, the deprecated version stops working. Once a version is no longer usable, any calls made to that version number will FAIL.

For example, Marketing API version 2.2 was released on October 30th, 2014 and Marketing API version 2.1 would expire on January 28th, 2015, 90 days after the release of v2.2. And actually it expired later than that date, on March 11th, 2015.

Here's a timeline example. 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 below, v2.0 will have been deprecated some time before v2.2 is released:

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 Marketing APIs or methods which no longer work, so you should assume an end-of-life SDK is no longer functional.

What happens if I don't specify a version for the Marketing API?

We refer to this as an unversioned call. Unversioned calls are invalid and will fail when made against Marketing API endpoints.

Can my app make calls to versions older than the current version?

An app can make calls to 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.

Here's an example:

  • If your app was created before the launch of v2.2, while v2.1 was available, then it will be able to make calls to v2.1 until the expiration date of that version. After v2.1 has been deprecated, calls to v2.1 will fail.
  • If your app was created after v2.2 was released, it will be able to make calls to v2.2 until the expiration date of that version, and any subsequent versions (v2.3 etc) until their expiration dates. After v2.2 has been deprecated, calls to v2.2 will fail.
  • Your app will not be able to make calls to v2.1, since 1) that was before your app was created and 2) that version is deprecated and all calls to v2.1 will fail.

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:

  • 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.

How is this different from Platform API versioning?

There are a few main differences between how Marketing API and the rest of the Platform APIs (a.k.a. Graph APIs) are versioned. For the full details on Platform API versioning, refer here.

  1. Marketing API is versioned on a 90-day deprecation schedule, whereas Platform API has the concept of core and extended APIs with a 2 year guarantee for core APIs.
  2. Marketing API does not support unversioned calls. Not specifying a working version in your Marketing API calls will cause the call to fail. Unversioned Platform API calls will be treated as v2.0 by choice via a Use Graph API v2.0 by default migration before April 30th, 2015, or enforced after that date.

Making Versioned Requests

All Marketing API endpoints are available through a versioned path. To do so, just pre-pend the version identifier to the start of the request path. For example, here's a call to v2.2

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. We will publish a full list of available versions in our changelog once the next version is announced. All of our Marketing API Reference docs will provide per-version information, so please check you're looking at the correct version - some versions remove nodes and edges, some versions will add nodes and edges.

How is this different from migrations?

Previously with migrations, you would go into your app settings and toggle a migration on or off, as described below. With the move to versioning, we are making Marketing API functionality more transparent by moving the setting into the endpoint, like so:

https://graph.facebook.com/v{n}/{request-path}

This allows developers of your tool to know immediately what behavior to expect out of an Marketing API call without having to manually go in and check the app's migration panel.

Now, you should no longer need to go into the migration panel and instead can rely on setting the version number in your Marketing API calls to take advantage of the new Marketing APIs.

Migrations

Migrations are reserved 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 will 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.

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. Please note, that the list of migrations may not be the same as in the image below, as the available migrations are differernt 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.

Temporary Client-side Activation of Migrations

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.