Planning for API v1’s Retirement

Tuesday, 5 February 2013

Back in September, we released the Twitter REST API v1.1 and announced that API v1 would be retired in March 2013. I’d like to provide you with more detail on the plan to retire API v1.

Who is affected?

If you’re a site owner that uses one of the older “goodie” widgets (e.g. profile, favorites, search and list widgets), you should move to Embedded Timelines as soon as possible. Likewise, if you’ve built your own widgets using unauthenticated client-side API calls, or if you or your widget consumes data from RSS or ATOM feeds, you should also migrate to Embedded Timelines. Unauthenticated requests are not supported in API v1.1.

If you’re a developer who has built applications with API v1, you should be moving those applications to API v1.1 now.

What will happen when API v1 has retired?

When API v1 is finally retired, all authenticated and unauthenticated requests to API v1 will return a HTTP 410 Gone status. Older widgets will receive the same response. This status code signifies that all API v1-era resources are gone and not coming back.

What dates should I be aware of?

We will perform the first of what we call “blackout tests” for API v1 on March 5th, 2013. We will not be permanently shutting off API v1 on this date. The @Anywhere framework will be permanently retired on March 5th, as planned.

What are blackout tests?

The blackout tests, which will take place on different days of the week and at varying times of day, are meant to help you better understand the impact the retirement will have on your applications and users. API methods will temporarily respond to requests as if the retirement has already happened — with an HTTP 410 Gone.

On March 5th, 2013, from around 9:00am to 10:00am PST, we’ll perform the first of these tests, limited only to unauthenticated requests. All unauthenticated requests during that time window will be responded to with a HTTP 410 Gone. Be sure to follow @twitterapi to receive notices before, during, and after the blackout test.

What’s next?

Over the next few weeks we’ll be announcing additional blackout tests and a more detailed schedule regarding the retirement of API v1.

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

Your API retirement cruise director,