Laying the foundation for API versioning

[Marcel Molina]

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

[Rich]

Great news guys, I noticed that the search and oauth API's aren't in
the version one API stream though.

Is this intentional?

[Rich]

I found the oauth one at http://api.twitter.com/oauth/ Is this the
new location rather than http://twitter.com/oauth/?

[Marcel Molina]

The OAuth endpoints aren't strictly speaking part of the REST API.

http://api.twitter.com/oauth/authorize and family works at the api
subdomain, but those paths aren't versioned (though maybe they should
be...). As for search...one step at a time ;-) But thanks for
noticing.

--

[Rich]

I did notice though that api.twitter.com doesn't have a valid SSL
certificate so any clients using the API over SSL will error out too.

On Oct 16, 8:49 am, Marcel Molina <mar...@twitter.com> wrote:
> The OAuth endpoints aren't strictly speaking part of the REST API.
>

> http://api.twitter.com/oauth/authorizeand family works at the api

> subdomain, but those paths aren't versioned (though maybe they should
> be...). As for search...one step at a time ;-) But thanks for
> noticing.
>

[Marcel Molina]

I've alerted our ops team. Thanks for the heads up.

[John Adams]

Could you let us know what errors you are seeing via SSL on
api.twitter.com? I'd like to investigate.

I do not see any SSL errors under Firefox and/or Safari on 10.5 nor
10.6.

-j

--
John Adams
Twitter Operations
j...@twitter.com
Follow me: @netik

[Rich]

Hi John, I replied directly to you, but didn't realise it was also
sent to the dev list.

Basically it seems to have gone now as I see the cert is a wildcard
one, this morning both the iPhone and Firefox were complaining that
the cert was for twitter.com and not api.twitter.com

Richard

On Oct 16, 11:04 am, John Adams <j...@twitter.com> wrote:
> Could you let us know what errors you are seeing via SSL on  
> api.twitter.com? I'd like to investigate.
>
> I do not see any SSL errors under Firefox and/or Safari on 10.5 nor  
> 10.6.
>
> -j
>
> On Oct 16, 2009, at 1:00 AM, Marcel Molina wrote:
>
>
>
>
>
> > I've alerted our ops team. Thanks for the heads up.
>

> > On Fri, Oct 16, 2009 at 12:56 AM, Rich <rhyl...@gmail.com> wrote:
>
> >> I did notice though that api.twitter.com doesn't have a valid SSL
> >> certificate so any clients using the API over SSL will error out too.
>
> >> On Oct 16, 8:49 am, Marcel Molina <mar...@twitter.com> wrote:
> >>> The OAuth endpoints aren't strictly speaking part of the REST API.
>

> >>>http://api.twitter.com/oauth/authorizeandfamily works at the api

[leonspencer]

Marcel,

Is the API description available as a markup file (e.g. XSD)? Or is
there some other way of programmatically scanning the APi that I've
missed.

Thank you,
Leon

On Oct 16, 12:26 am, Marcel Molina <mar...@twitter.com> wrote:
> 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 athttp://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 tohttp://twitter.comwill no longer be serviced. We aren't planning on

> pulling the rug out from anyone though. Please update your

> applications to the newhttp://api.twitter.com/1at 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 onhttp://api.twitter.com/1but we hope to

> havehttp://api.twitter.com/2close around the corner. The time has
> come for us to start knocking off some of the stuff on V2 Roadmap listhttp://apiwiki.twitter.com/V2-Roadmap. For a while that page has been

[Thomas Woolway]

Hi John,

I'm still getting SSL issues with api.twitter.com - it seems like some attempts get the wildcard certificate, some get the old one. This is using Chrome and AIR.

Let me know if you need any more information,

Tom

[Dave Briccetti]

DELETE http://twitter.com/friendships/destroy/USER.xml

works, but

DELETE http://api.twitter.com/1/friendships/destroy/USER.xml

fails with

You don't have permission to access /1/friendships/destroy/USER.xmlon
this server.

[Marcel Molina]

Thanks for the report. Looking into it.

--

[Marcel Molina]

This was an oversight in a server configuration. We've made the change
and should be pushing it out at some point today. Thanks again.

On Fri, Oct 16, 2009 at 12:55 PM, Dave Briccetti <da...@davebsoft.com> wrote:
>

--

[Dave Briccetti]

Thanks, but still failing today.

[Marcel Molina]

The change has been made but it probably hasn't been pushed out yet to
the full cluster. I'll follow up with ops on Monday. Thanks.

On Sun, Oct 18, 2009 at 1:10 PM, Dave Briccetti <da...@davebsoft.com> wrote:
>
> Thanks, but still failing today.
>

--

[Sal Conigliaro]

Hi Marcel-

I'm still seeing the cert hostname mismatch.

https://api.twitter.com/1/users/show/rwzombie.xml

The cert hostname returned is still shown as 'twitter.com'.

Sal

[Marcel Molina]

Ops is working on fixing this. We identified some stale configurations
on some hosts (which is why the failures are intermittent). It's
currently being worked on and should be resolved soon. Thanks for
reporting it.