Laying the foundation for API versioning

4,717 views
Skip to first unread message

Marcel Molina

unread,
Oct 16, 2009, 3:26:24 AM10/16/09
to twitter-deve...@googlegroups.com, twitter-ap...@googlegroups.com
We've taken the first steps toward introducing versioning into the
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

Reply all
Reply to author
Forward
0 new messages