APIs are now the cornerstone of most product offerings. Early API Providers are now at a stage where their early API offerings have been truly tested by developers. In their quest to fine tune their API, these organizations have mined through usage patterns, API bottlenecks and many more parameters to help understand what they could have done different if given a chance (read that as version 2.0). Kevin Montrose of Stack Exchange, one of the most popular collections of Q&A sites, has published a couple of blog posts on the good and bad parts about the Stack Exchange API, that provides a good lesson to all of us.
The first post focuses on the thought processes that went into version 1.0 of the API and what they set out to achieve. Kevin goes on to explain the rationale behind making version 1.0 read-only. Given the fact that various sites wanted to scrape as much of their information, their next focus was to eliminate the need to scrape by giving an API equivalent for top level data like users, tags, questions, etc. Other points include allowing a combination of ids in the API requests, forcing all responses to be GZIp’d and various parameters in the API calls like sort, min, max, fromdata, todata to allow for filtering and sorting.
The second post builds upon the previous one by discussing the mistakes of version 1.0 and some of them are interesting and only companies with a large adoption of their API would encounter. One particular one which seems innocuous at first is that of returning a total by default. For example, every method in the API returns a count of the elements the query would return if not restricted by paging. As a user you may or may not use that. But it is a cost for their API to compute that total whether you want it or not. In an interesting graphic, it costs as much time to get the total as it takes to fetch data.
Other mistakes mentioned in the article include the return of implicit types in the results, thereby making writing client wrappers difficult. That’s a key part since now most API providers are expected to either provide client wrappers in multiple programming languages or make it easier for developers to churn them out. A “Focus on Registered Users” and “Wasteful Request Quotas” are other mistakes and make for excellent reading to understand key API design problems.
Kevin Montrose states that there is going to be a series of articles on the mistakes that they have made while producing API version 1.0. We cannot wait for more. While one can call them mistakes, for those who learn from them they will be lessons upon which the next generation of well designed APIs will be built.