Laying the foundation for API versioning
Marcel Molina
Twitter REST API. With a versioned API we can make ambitious
improvements *today*, not tomorrow, without worrying about breaking
backwards compatibility. This will lead to both a better and more
reliable API.
Available right now, the API's new home is at http://api.twitter.com.
Currently only one version is supported: version 1 :-) Version 1
should be in all ways functionally equivalent to the API you're using
at the main twitter.com url (if you find what seems like an
incompatibility please submit what you've found on our issue tracker:
http://code.google.com/p/twitter-api/issues/list).
To make a request with the new versioned API, you just need to prefix
every path with the desired version. For now that's just 1.
So for example, what was
http://twitter.com/users/show/noradio.xml
becomes
http://api.twitter.com/1/users/show/noradio.xml
For now we're keeping it simple. No subversions, no implicit version
defaults, no fancy-pants etc. We're leaving our approach open to these
types of additions, but we aren't going to support them until we feel
a compelling need to.
We haven't yet determined how many versions will be supported at once
or how long a version will continue to be supported once it's
deprecated. We'll be figuring out answers to these questions once we
spend some time supporting multiple versions and seeing how new APIs
emerge and iterate. We suspect though that we'll support deprecated
versions for at least 6 months.
We also don't have a hard date for when API requests to
http://twitter.com will no longer be serviced. We aren't planning on
pulling the rug out from anyone though. Please update your
applications to the new http://api.twitter.com/1 at your soonest
convenience. The non API urls likely won't be supported forever.
Though having a versioned API should greatly decrease the likelihood
that a change in the API breaks your application, one of the notable
exceptions is bug fixes. When bugs are discovered they will be fixed
and backported immediately to all supported versions of the API.
We're kicking the tires on http://api.twitter.com/1 but we hope to
have http://api.twitter.com/2 close around the corner. The time has
come for us to start knocking off some of the stuff on V2 Roadmap list
http://apiwiki.twitter.com/V2-Roadmap. For a while that page has been
the dumping ground for all our lofty dreams. Version 2 probably won't
be so ambitious that it resolves everything on that list. We want,
after all, to get good at managing a multi-version environment before
we get all crazy with the nitrous injections and chrome detailing. But
we're putting the framework in place that will allow us to more
quickly fix the stuff you've struggling with, take chances without
putting your work in jeopardy, and all other things that are good.
Cheers.
--
Marcel Molina
Twitter Platform Team
http://twitter.com/noradio