What’s a Good API?

API, or Application Programming Interface, is a term that has nearly become synonymous with Web API’s of late. Simply put, an API of this sort offers interaction with a server system over HTTP, delivering data as XML or JSON. I was recently asked in a job interview “What makes a good API?” I answered reasonably, but it got me thinking. Here’s a brief but more thoughtful answer, informed by recent real experience with Facebook, Flickr, Amazon and Twitter.

A good API has to value consistency as near religion. An ideal API experience for a new client of that API should require no documentation reading at all, assuming the client author knows what data she’s trying to pull from the provider. REST has gone a long way towards standardizing how this can, and perhalps should, be done. Twitter, for the moment, suffers a painful inconsistency between it’s standard REST API and the very useful search API. Granted, search is provided through the recent acquisition of Summize and the cobined Twitter and former Summize teams fully intend to address the inconsistency.

Orthogonality is another cornerstone. There should be very little magic done behind an API call, in that if I ask for something, I should get back just that something (or a clean list of somethings), in a more-or-less canonical form. Magic is tempting to add for convenience to clients, but it leads to overlap, and hence non-orthagonality. For maximum use and reuse, and interface might even require multiple calls, where one magic one would have sufficed, in order to retrieve the data a client needs. In essence, I mean that no side effects, good or bad, can result from a call for some data. I love the term “Principle of Least Astonishment” to embody thought that no one should be surprised by anything your API does. Although the API may ultimately become large, orthogonality as a principle of design will keep it relatively compact and obvious to client developers. They don’t have much interest in reading documentation, most likely, but a few well-written practical examples demonstrating this idea will be good enough for nearly all needs.

Smart version handling and clear policies must be in place at the inception of a good API. It’s got to have a supportable version policy (that is, how many versions will be supported and for how long?), and a simple version exchange protocal so that clients can report the version the support and expect, and servers can respond with their version and level of support for a particular client call. Further, friendly deprecation of API methods is a way to soft-fail calls that are going to be removed or re-purposed in the next version.

Things ought to be named intuitively. When the team at Digital Railroad took on API design, we made sure to eat our own dog food and be the first users of whatever resulted. Naming proved to be an unexpected challenge. I found that if we couldn’t name it easily, something about the design was likely amiss. Flickr and Amazon in particular have done a nice job of simple, consistent naming in their REST API’s.

Errors should be informative and specific, but use standard HTTP error codes. I worked with a technology provider in the photo world, who shall remain nameless here, that built a reasonably large API. It violated nearly all of the points I put forth here, but the most aggregious was in the area of error reporting. Imagine working with a method that takes no less than 20 parameters, then returns a “-1” upon failure in the body of an HTTP 200 response, with no additional diagnostic info! This is extreme, but really happened until we ultimately shelved the project due in large part to this kind of API nonsense.

There are more real-world principles of good API design, so shoot me yours.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s