Versioning

Overview

We are introducing a versioning strategy in our efforts to build a stable and reliable Twitter API. Developers can know when to expect changes to Twitter’s public APIs and be given time to migrate to new versions. Developers will be notified of deprecations/retirements, and changes and additions to the public API so they can appropriately plan to accommodate these changes in their development roadmap. All changes to the API will be noted in the changelog.

The Twitter API currently has two different versions. To learn more about each, please visit the following pages:

 

Versioning Strategy

Versioning for the Twitter API will be represented by version numbers declared in the route path for our endpoints:

https://api.twitter.com/2/tweets

We aim to release major versions of the public API as necessary no more than every 12 months. A major version will be released when breaking (outlined below) changes are introduced in the API. We will publish migration guides when launching a new major version to help developers migrate over to the new version. A breaking change requires developers to change their code to maintain existing functionality in their app. Non-breaking changes will be additive and rolled out to the most recent version when ready, requiring no work on a developer’s end unless you would like to take advantage of the new functionality.

If a breaking change must be rolled out mid-cycle (for security or privacy reasons), this change will be made to the most recent version.
 

Breaking changes

These changes require developers to change their code to maintain existing functionality of their application.

  • Addition of a new required parameter
  • Removal of an existing endpoint
  • Removal of any field in the response (either required or optional)
  • Removal of a query parameter
  • Restructuring of the input or output format (for example, making a top-level field a sub-field, or changing the location of errors to be inline)
  • Changing the name or data type of an existing input parameter or output value
  • Changing the name of a field
  • Changing the resource name
  • Changing a response code
  • Changing error types
  • Changes to existing authorization scopes

 

Non-breaking changes

  • Addition of a new endpoint
  • Addition of a new optional parameter
  • Addition of a new response field
  • Reordering of fields
  • Changing text in error messages
  • Availability of new scopes
  • “Nulling” of fields (changing the value of a to null for privacy/security reasons as an alternative to removing it altogether)

 

Deprecation

As soon as a new version is released, the previous version will be marked as deprecated. Versions will remain in a deprecated state for one year, after which they will be retired. In effect, any version will be available for at least two years overall, including their deprecation period. Any calls made to versions after they are retired will fail.

 

Was this document helpful?

Thank you

Thank you for the feedback. We’re really glad we could help!

Thank you for the feedback. How could we improve this document?

Thank you for the feedback. Your comments will help us improve our documents in the future.