Home Mistakes Made and Lessons Learned from the Stack Exchange API

Mistakes Made and Lessons Learned from the Stack Exchange API

There’s no better way to learn than by making mistakes. Just ask Kevin Montrose from Stack Exchange. Montrose is going a post-mortem on the first generation Stack Exchange API, with coverage of its history and mistakes made in its design.

The first post is about the history of the API and some of the things that they did right (or at least intentionally). For example, deciding that with the first version of the API, it would be read-only. Says Montrose, “we didn’t have the resources to devote to the mounds of refactoring that would be required to get our ask and edit code paths up to snuff.” Knowing how much to bite off with the first attempt, while still satisfying the developers who need the API, is important. Montrose also notes that write access via an API is “incredibly dangerous,” and they wanted to push that out to deal with it properly. Look for write in the 3.0 version of the API.

Montrose also says that forcing all responses to be GZIP’ed was a good call. “Not GZIP’ing responses is a huge waste for all parties. We waste bandwidth sending responses, and the consumer wastes time waiting for the pointlessly larger responses (especially painful on mobile devices). And it’s not like GZIP is some exotic new technology, no matter what stack someone is on, they have access to a GZIP library.”

So what did they get wrong? A big one is returning text via the API that’s not safe to embed in HTML. “This led to the situation where question bodies are safe to embed directly, but question titles are not; user about me’s, but not display names; and so on. Ideally, everything would be safe to embed directly except in certain rare circumstances.”

Many of the other mistakes fall under the category of “incorrect assumptions.” The API returns a “total” field by default that shows a count of the elements a query would return. Developers might want the total, but they don’t always want this, so it’s a waste when they don’t. The 1.0 API also returns implicit types for results, which Montrose says “makes it something of a pain to write wrappers around” for statically typed languages.

The good news is that 2.0 of the API is planned for later this year and 3.0 is in planning stages. None of the mistakes here are fatal, and they’re being addressed.

Kodos to Stack Exchange and Montrose making this available, I do hope they continue the practice. For many developers, this sort of thing is largely theoretical until they actually work on a project with a diverse developer base consuming the services. For many companies, the process is a black box. By talking openly about the problems with their APIs and how they intend to fix them, Stack Exchange is passing on some interesting information as well as giving their developer community a better chance to provide feedback.

For the developers in the audience, what other do’s and don’ts do you see with APIs frequently?

About ReadWrite’s Editorial Process

The ReadWrite Editorial policy involves closely monitoring the tech industry for major developments, new product launches, AI breakthroughs, video game releases and other newsworthy events. Editors assign relevant stories to staff writers or freelance contributors with expertise in each particular topic area. Before publication, articles go through a rigorous round of editing for accuracy, clarity, and to ensure adherence to ReadWrite's style guidelines.

Get the biggest tech headlines of the day delivered to your inbox

    By signing up, you agree to our Terms and Privacy Policy. Unsubscribe anytime.

    Tech News

    Explore the latest in tech with our Tech News. We cut through the noise for concise, relevant updates, keeping you informed about the rapidly evolving tech landscape with curated content that separates signal from noise.

    In-Depth Tech Stories

    Explore tech impact in In-Depth Stories. Narrative data journalism offers comprehensive analyses, revealing stories behind data. Understand industry trends for a deeper perspective on tech's intricate relationships with society.

    Expert Reviews

    Empower decisions with Expert Reviews, merging industry expertise and insightful analysis. Delve into tech intricacies, get the best deals, and stay ahead with our trustworthy guide to navigating the ever-changing tech market.