30

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.

Additional Notes

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.

5
  • 1
    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? Feb 12, 2011 at 0:23
  • 1
    @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. Feb 12, 2011 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? Feb 12, 2011 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. Feb 12, 2011 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? Feb 15, 2011 at 11:37

1 Answer 1

3

Thank you!

All of the new changes are welcome and I can't wait to start implementing some of them in my apps.


I do have one question though: what happened to all of my apps? I had a thumbnail image set for all of them and it doesn't look like any of them are being displayed despite matching the requirements (144x119 in PNG format).

Edit: This doesn't seem to be the case for all of them. Just some of them.

12
  • I'd guess Jeff got a little over zealous with generating thumbnails for apps, just revert it to whatever it was before if you don't like them. Feb 11, 2011 at 23:23
  • @Kevin: Okay. I've rolled those ones back. Feb 11, 2011 at 23:36
  • @kevin I generally didn't touch George's images, and everything I did touch loads fine in my browser. I did mention to you that I was seeing a little imgur weirdness though. Feb 11, 2011 at 23:55
  • @Jeff - ah, I thought the wrong image was being displayed not no image. My bad. Feb 11, 2011 at 23:57
  • @kevin I had to lock those posts because I'm pretty anal about the thumbnails looking good. I see no issues with the imgur on my side, but apparently George does. Feb 11, 2011 at 23:58
  • @Jeff: I'm confused... what's up? Feb 12, 2011 at 0:15
  • george, we prefer the thumbnails to communicate something about what the app does -- take a look at the homepage and see what I mean. We'll unlock these later, it sounds like you were confused about what was on the page, and this isn't an "images not loading" issue. Feb 12, 2011 at 0:15
  • @Jeff: Okay, I understand that... I just didn't realize what was happening. Will the posts be unlocked so I can edit them for other reasons? (Version updates, new features, etc.) Feb 12, 2011 at 0:18
  • @george yes definitely. I apologize for the confusion. We just want to make sure everything is looking its best for the launch. :) Feb 12, 2011 at 0:27
  • @Jeff ouch, logos are not welcome? Feb 12, 2011 at 0:50
  • @Jeff: Also, would it be possible to have the thumbnail for StackMobile be a screenshot of the home page? Feb 12, 2011 at 3:29
  • @system I clarified the policy here: stackapps.com/questions/2003/… we reserve the right to exert editorial control over the thumbnail images because they need to communicate clearly to the average user what the app does. Feb 12, 2011 at 4:54

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .