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?
