ASSERT: Learn by Testing

My 6-year-old daughter received a microscope kit as a gift. It’s not the 50’s-style die-cast behemoth I had as a kid, with all it’s frustrating sample mounting and focus issues. No, this is 2009, and this perfect kids’ ‘scope requires no focusing and is small enough for her to wear as a necklace. And, it’s pink which makes the necklace prospect all the more attractive.

I’ve been teaching her a little bit about science and encouraging her questions. But really, I am passive, watching her formulate theories and test them. Our freezer is full of “samples” from the last Brooklyn snowfall.

She is learning to learn by testing, to come up with an assertion she believes to be correct, and then by observation rule it in or out. The application to programming and building systems is obvious, but easy to forget. I’ve sometimes fallen into the trap of assuming something is true, and relying on that assumption without a proper assertion and test. With the overwhelming amount of reading material available on what works and what doesn’t from “cloud computing” to scaling Ruby, from development environments to search algorithms, it’s easy to fall back on assumptions, most often and dangerously someone else’s assumptions. Watching my daughter’s inner scientist emerge has been a good reminder for me.

I now assert, and have proven, that even New York City snow is made of ice crystals and melts at room temperature.

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.