Web API Design: The Good, The Bad, and the Ugly

Two recent events have prompted me to spend a lot more time thinking about API design: 1) A series of "Good, Bad, and Ugly" talks at the Google Sydney office which examine internal architectures and coding decisions, 2) An internal reading group starting with "Beautiful Architecture", a book of essays. Though the design of internal software (largely the focus of the talks and book) is important and should be done well, it's my opinion that the design of external-facing Web APIs is even more important, and yet, a much less discussed topic.

Why? Web APIs have some unique challenges:

Flexibility: Web APIs are intended to by whatever random developer finds them useful, not by a restricted set of internal developers. And, I can tell you from experience, random developers do things that you never even realize was possible with your API - and then they beg for feature requests to make it easier for them - and you'll want to fulfill their requests because you'll think "hot damn, that was cool!" So, the easier it is to implement new and different features, the better.

Backwards-Compatibility: Web APIs have to stay around for a long, long time. Even if you threaten that you'll change your API every 2 years and you warn users 1 year ahead of time, you'll still have some developers use the old version of the API and write angry posts in your forum about their site breaking. Or, developers that have written code for client sites, moved on to bigger and better things, and left it with webmasters that have no idea how to upgrade it. Or, developers using wrapper libraries that abstract on top of the older version of the API, and have no notion of the underlying API. So, it's safe to assume that you can never really deprecate an API without breaking old sites, and you should design the API with that in mind (future-proof it).

.. and other challenges, like needing to be equally usable by both newbie and advanced developers, and needing to be a reasonable number of kilobytes (for client-side APIs).

In the land of Web APIs, the Google Maps API makes for an interesting case study. It is one of the most used Web APIs in the worlds (150,000 sites), the first interactive web mapping API, likely the first hosted JavaScript API, and it has grown from a simple API with just markers and zooming to a complex API with 90+ classes. It's also gone from version 1 to version 2, but the changes were primarily in terms of latency; the actual interface has remained largely the same. All these facts make it interesting to look at the Maps API from an architecture and design point of view, and point out the places where it went right - and where it went wrong. Of course, as an advocate of the Maps API and someone who uses it daily, I should point out that I still think we have the best Maps API in the world. But even gods can have their flaws (I hear Zeus had a weakness for mortal women).

So, in an upcoming series of blog posts, I'll single out design decisions in our API that I think were good, bad, or ugly. To start it off on a good note, I'll start with something beautiful... stay tuned!