Versioning is coming to Twitter’s Ads APIs

Every month, we make changes and roll out several new features on our Ads API. These changes are nearly always backwards compatible, but we do tend to have a handful of breaking changes each year. We’ve received feedback from you on the challenges that our fast cadence of changes in the Ads API has on your development cycles when it comes to implementing new features, handling deprecations and testing changes. We want to improve the developer experience using our Ads Platform, and later this quarter, we’ll begin to version changes we make to our Ads API.

What to expect

Whenever there’s a change in behavior, we’ll bump the version number in the API. Versioning is something developers are already very familiar with, and we’re implementing a semantic versioning scheme like others you’re used to. This provides an easy and clear way for developers to know what changed, when and plan for their implementations on that change. Our versioning will expose both the MAJOR and MINOR number of a change. For example, a version could look like 2.3. All breaking, backwards incompatible or significant changes will increment the MAJOR portion of the version, and backwards compatible changes will increment the MINOR portion.

For example:

• If the current version of the Ads API is 2.0 and we add a new set of attributes that expose the Twitter screen_name on the promotable_user object, this would be a backwards compatible change and we’d bump the version to 2.1.
• In a subsequent change, if we removed the user_id attribute from the same object, this would be a backwards incompatible change and would require a MAJOR version bump, so this change would be introduced in version 3.0.

For the Ads APIs, we’ll move from the current 30-day deprecation window to a minimum of at least 90-days support for the deprecated version, once a new version has been released.

Due to the nature of the changes we often make to our Ads API, developers only need to request the MAJOR version they’d like, as all changes will be backwards compatible. So that developers can track what has changed between MINOR versions, we will return the current MAJOR.MINOR in the response headers and include change logs of each in our developer docs on dev.twitter.com.

• Developers will continue to pass the version of the API they would like to interact within the resource URL of their requests
• We’ll begin to return a new header in all API responses: x-api-version: 1.1
• All API calls will continue to require a version be specified

We’re excited to better support our developers in our Ads APIs moving forward, and to see what you build using the Twitter Ads Platform!