API Housekeeping

When we originally released the Twitter API back in 2006, little thought was given to API design patterns like explicit versioning, subdomain partitioning, and response structures that would scale with the rapid but unexpected growth of the Twitter service and platform. Over the past two years we’ve continued refining and upgrading our original API and the monolithic infrastructure that powered it. Now that “version one” of the REST API has solidified on api.twitter.com, we’re ready to do some housekeeping to tidy up remnants of the past that cause both developer confusion and operational inefficiencies.

We will sunset all unversioned endpoints and previously announced deprecated methods on Monday, May 14th, 2012. We’ve frequently recommended that developers avoid these outdated and often long-undocumented alternative endpoints and it’s time for them to be removed.

We’re also taking the opportunity to make default some behavior that previously has only been enabled through query parameters on May 14th: timeline methods that previously required the use of “include_rts=true” to respond with retweets will now return them regardless of the provided parameter. Additionally, we’ll begin including the metadata-rich Entities in Twitter Objects in all methods currently supporting the “include_entities=true” parameter. Finally, we’re re-emphasizing efficient timeline access patterns by favoring the usage of since_id & max_id over the unscalable “page” method.

To recap, on May 14th, 2012:

• All non-versioned API endpoints, such as http://twitter.com/statuses/user_timeline.xml, will cease functioning and you’ll need to use the proper endpoints instead. See the deprecated methods for more.
• All previously announced-as-deprecated methods will cease accepting requests.
• GET statuses/public_timeline will also be deprecated. Please use the Streaming API’s sample endpoint to obtain a sampling of public tweets.
• OAuth 1.0A operations must be performed on the api subdomain. Older http://twitter.com/oauth/* paths will cease to be functional.
• Atom is being removed on all methods currently supporting it as an output format due to disuse. RSS will remain available on these methods.
• All API methods capable of including Entities in Twitter Objects will return them regardless of the value provided by include_entities=true
• All API methods capable of including retweets will return them regardless of the value provided by include_retweets=true
• All methods currently supporting cursoring or usage of since_id and max_id will remove support for “classic” pagination through the “page” parameters. See Working with Timelines for more information.

Please ensure that you’ve moved from any deprecated endpoints by May 14th, 2012 to maintain application functionality. Not only do these updates make everything run more smoothly now, but they’re also an important step in allowing the platform to continue growing at scale.

If you have any questions or concerns, please direct them to this thread.

Thanks,
the Twitter Platform Team

Schedule Update

May 10, 2012: Thank you for your continued efforts in preparing for the upcoming deprecations. Based on your feedback, we’ve decided to more incrementally phase these deprecations over the next several weeks. Stay tuned next week for an updated deprecation schedule. None of the currently scheduled changes will take effect on May 14th, 2012 but we still encourage you to continue implementing the necessary changes in your applications.