Announcing API version 1.1

As has been announced on the blog, we're rolling out a minor revision of our existing read-only API.

While the blog post gives some high level details, I figured [app] developers would appreciate some more nitty gritty details on what's version 1.1 is all about and where the API is going in the future.

Version 1.1

We're considering this a minor release, this means:

• Versions 1.0 and 1.1 will share the same life-cycle, being deprecated and retired at the same time.
• Primarily new methods, as opposed to new versions of existing methods.
• Strictly backwards compatible, no breaking changes allowed.

To be absolutely, 100% clear, no clocks have started ticking on version 1.0. We've always said that we'll support anyone who builds on our platform, but I still want to emphasize that.

18 new methods have been added, 2 older methods have been revisited (their old versions still available, naturally), and documentation has been improved.

There have also been some behind the scenes tweaks to speed up some existing routes, and common use cases. /search in particular should be much faster.

Two things have been deprecated, but not yet removed for backwards compatibility reasons. These are the old help system, and any view_count data (including sorting on it) related to answers.

While 1.1 is not considered to be in beta (I anticipate no new methods or interface changes), it has naturally seen much less real-world usage than 1.0. As always, if you find a bug please post it here on Stack Apps.

We're not exposing election information, or suggested edits at this time as both features are still in a non-trivial state of flux.

Version 2.0

While I'm hesitant to publish a schedule (Stack Exchange is simply growing and changing much too quickly for any reliable scheduling), I do see the value in giving developers a road map.

For version 2.0, the biggest new feature will be user authentication. Currently leaning towards OAuth2.0, although this is subject to change. As a consequence, access to some private information (inbox notices, some voting records, maybe contact information, etc.) and privilege restricted information (deleted posts, flags, and so on) will be possible.

Also expect the "form" of API responses to change (the new Stack Auth methods are experimenting with some of these changes), and for the ability to request only a subset of the fields on an object. These changes will be aimed at making it easier for [app] developers to tweak performance and data consumption, as well as fixing some pain points when dealing with the API in statically typed languages.

With any luck, we'll be working on this version sometime this calendar year. Given the scale of the planned changes, I expect it to take a full 2 months to get it into a beta-able state.

Version 3.0

Version 3.0 will be all about write access. Frankly, write access is incredibly dangerous, and quite complicated, so it really needs a whole release just to itself.

We put a lot of effort into keeping garbage out of the Stack Exchange network, and all of them have to apply to the API (in a way that doesn't drive developers insane). It also can't break every [app] when we add a new trick to our arsenal, so the design needs to be pretty flexible.

We also have to figure out how to make it possible (I doubt we'll actually be able to pull off easy) for [app]s to render Markdown, especially with the various extensions some sites may have. Currently we have Prettify, MathJax, and jTab but more could be added at any time.

Developers should expect write access to be linked in some way to user reputation as well. Its quite likely that a 1 reputation user will be able to do nothing (or only the most safe things, like comment on their own posts) via the API, while higher rep users will be able to do essentially everything they normally can. One caveat, I currently have no intention of ever exposing any moderator level abilities via the API.

We naturally reserve the right to change all of this, but it reflects our current plans for the future of the API.

Should scheduling difficulties push any of these versions back substantially, [app] developers can expect a minor revision which would add any pressing new features that had been added to the network in the meantime.

-
good job, I really like the pimped documentation. One question: I have noticed that you have introduced the markdown_extensions parameter on /sites route, are you going to mark as status_completed that feature request? Are there any other features added that were marked as status_planned and now are status_completed? – systempuntoout Feb 12 '11 at 0:23
@systempuntoout - yeah. Some other are probably, I'll need to go and do a sweep of old questions to find them all and update them. – Kevin Montrose Feb 12 '11 at 0:24
sorry for the dumb question..one thing that I don't get is why /sites route and other routes in the documentation have This method is new to version 1.1 description. Is it new or just updated? – systempuntoout Feb 12 '11 at 0:46
@system - the version of /sites that page documents is new in that it's completely incompatible with the old one. Of course, for compatibility's sake the old one is still around. I guess I should clarify that in the documentation. – Kevin Montrose Feb 12 '11 at 1:47
I know it is only after V3, but will there be at least the ability to retrieve the mod flag messages, or a count of the number of moderator flags at some point? Also will you at one point be willing to review the moderator ability features? – Diago Feb 15 '11 at 11:37