Alex Barnett blog


Web API Design - Keep Some of it Simple, Stupid

Tim O'Reilly's latest post includes a paragraph that for me at least, encapsulates the character of the transition the web is going through today. I want to call it out here:

"In my talks on Web 2.0, I always end with the point that "a platform beats an application every time." We're entering the platform phase of Web 2.0, in which first generation applications are going to turn into platforms, followed by a stage in which the leaders use that platform strength to outperform their application rivals, eventually closing them out of the market. And that platform is not enforced by control over proprietary APIs, as it was in the Windows era, but by the operational infrastructure, and perhaps even more importantly, by the massive databases (with network effects creating increasing returns for the database leaders) that are at the heart of Web 2.0 platforms."

I'd like to make an additional point on this topic and it is this: Aside from the quality and value of the data residing in these networked datastores and the functionality exposed via the APIs by competing platform / application / service provider players, it will be the usability of these APIs and their adoption that will determine who wins and loses in the web platforms and application wars to come.

APIs can come in all sorts of flavours. At one end of the scale you have the complex APIs. By complex I mean that they are based on technologies - I'm thinking of WS* here - that require a certain level of technical competence by the users (developers) that want to use them. These complex types of APIs will often require sophisticated toolsets that demand a skill level disciplined by training, and therefore will be beyond the reach of a large and growing population category of developers, what some refer to as the hobbyist developers. Today's web is made in large part by these hobbyists.

On the other end of the scale are the simple APIs. These are designed not just with the hobbyist developers in mind, but also the professional developers too (perhaps unintentionally in some cases). Professional developers are smart and lazy. They want to do the least amount of work possible for the most return. Simple APIs lower the barriers to adoption for these developers too and can make things easy to do. In a web as a platform world, this matters: the more adopters of your APIs (and therefore your platform) there are, the better your platform does.

RSS is the case in point here. It is simple, really really simple and it's simplicity is precisely the reason why it has become the de facto content API standard. Arguably, the key developer segment that helped ensure RSS become the #1 XML standard on the planet is the hobbyist developers, the builders of the amateur web, who could understand the simple API that exposed content and run with it. Before you knew it everyone was using it, including the professional developer community.

I am not suggesting that APIs designers take an either / or approach here. In a perfect world, platform / application service providers should provide a portfolio of API services that range the ease-of use-spectrum.

Powerful APIs are complex because they expose powerful functionality and developers like powerful functionality. However, from a design perspective, I think too many APIs designers (read: platform designers) start from the complex end of the API design spectrum with the goal of providing all-dancing and all-singing APIs and then work their way down to the simple stack. Complex APIs take time to design, develop and test and no application development team I've ever come across has infinite resources, so they have to start somewhere and they often choose to start at the hard-skill end of the continuum. A mistake in my opinion.

eBay and Amazon are great examples of how they have understood the need to provide a range of APIs that allow all-comers, regardless of technical skill to join their party. From simple 2-step wizards that output simple strings of JavaScript code, to simple RSS feeds, to RESTful APIs to full on WS*-based web services exposing a dazzling array of functionality, these web platform providers have built out huge developer communities that can pick and choose what they require according to their needs. The members of their developer communities vary hugely in terms of skillset and this is no accident. Their business models rely heavily on the adoption of their APIs.

So, my point is this: if you are involved in the design of APIs for the web (this includes those designed for use inside of the firewall - aka Enterprise 2.0), do yourself, your userbase and everyone else a favour: Keep Some of it Simple, Stupid.

Posted: Oct 28 2006, 08:10 AM by alexbarnett | with 1 comment(s)
Filed under: ,