Atlas API Versioning

Facebook's Atlas 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 July 19th, 2015, Atlas API will move to a versioning scheme to manage changes in the API. With versioning, all breaking changes will be rolled up into a new version. Multiple versions of Atlas APIs 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 Atlas API might change. While you still have a 180-day window to adopt changes, the decision of how and when to move to the new version is yours.

Version schedules:

The most recent version of the API is v2.7, which was introduced on July 13th, 2016.

VersionPathDate IntroducedAvailable Until

v2.7

/v2.7/{object}

July 13, 2016

v2.6

/v2.6/{object}

Apr 12, 2016

Oct 2016

v2.5

/v2.5/{object}

Oct 7th, 2015

July 13, 2016

v2.4

/v2.4/{object}

July 8th, 2015

April 11, 2016

v2.3

/v2.3/{object}

May 15th, 2015

July 19th, 2015

Note that the first version of the Atlas API is v2.3 which will not following the regular breaking change schedule. You will only have until July 19th to move to v2.3, otherwise all your unversioned Atlas API calls will fail.

How much time do I have to implement changes?

When a new version of the Atlas API is launched, we'll continue to support the previous version of the Atlas API for at least 90-days. During the 90-day deprecation period, both versions of the API will be callable (the current version and the deprecated version).

See below diagram for how the release schedule is rolled out:

So as a developer, from the day when a breaking or a version update is announced, you will have total 180 days to implement the changes.

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

We refer to this as an unversioned call. Unversioned calls are invalid and will fail.

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

An app can make calls to the version of the Atlas 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.

Do I have to do anything if the API calls I am making is not in the list for annouced breaking changes?

No, you do not have to. When there is no change in the API, Atlas platform will automatically bump the versions for you. Hence your code base does not have to make change if there was no change to the API.

How is this different from Platform API versioning?

There are a few main differences between how Atlas 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. Atlas 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. Atlas API does not support unversioned calls. Not specifying a working version in your Atlas API calls will cause the call to fail.

Atlas Versioned Requests

All Atlas 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.3

curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/v2.3/me/atlascampaigns"

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 Atlas 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?

With migrations, you would go into your app settings and toggle a migration on or off, as described in migration document.

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