The Little Manual of API Design

While flipping through some of the blogs on my reading list this evening, I came across a link to "The Little Manual of API Design" by Jasmin Blanchette. If you're a software developer reading this, I strongly encourage you to read, absorb, and internalise the lessons presented here. Furthermore, as the article I found this link from argues, if you're a user interface designer, you probably also want to read and understand this, since API's (Application Programming Interfaces) are still a form of interface for communication between humans, computers, and other humans, so the concepts presented here do carry over.

Without further ado, here is the link (from Blanchette's website):

http://www4.in.tum.de/~blanchet/api-design.pdf

For anyone who has read any of my previous rants about the state of various toolkits, you'll know that my outright favourite toolkit is Qt. Of all the toolkits I've worked with, IMO it's one of the best examples of a really well thought out and engineered piece of software that I've seen. Compared to many different API's other there, this one feels solid, comfortable and easy to use, especially once you pick up the way that it does things. For example, its internal logic is impeccable. That is, there is a nice consistency to the way things work in the Qt API's which IMO is one of its real strengths, as it feels like a coherent whole that was conceived of by the same bunch of well grounded architects instead hack and slash dogwash by an evolving tribe of savages. In addition to this, it is also quite flexible, to the point that it can be pushed quite far to produce some new designs/techniques (important when doing things like I was doing in my Honours Project last year). Sure, as with any piece of software, there are always one or two warts that you'll inevitably encounter, especially when you start pushing things to the limits (and beyond, as is often the case in some of my research projects), but hey, by and large the people behind this have done a very thorough job.

This is a far cry from most of the other toolkits out there.

• For example, the antiquated verbosity and vulgarity of GTK (Blegh! What rubbish... I never want to work with this vile festering pile of crap ever again...). Besides having bad defaults, odd runtime behaviours, many different API styles for different sections (and even multiple styles of usage for individual areas), deprecated feature subsets changing vigorously with each and every point release, it often feels like an absolute dog to work with due to the verbosity of all the methods and the amount of "manual labour" that often must be done to get things playing nice.
• Another example is Java Swing. Having spent the better part of a year and a half fighting it in the past, it's really not something I'd really recommend that anyone use for serious projects. While it may have been somewhat acceptable maybe 15-20 years ago, it falls quite short these days due to the amount of hackery needed to implement now-standard behaviours/functionality that it doesn't provide by default. Speaking of defaults, the defaults it has are mostly obsolete choices nowadays which need to be overridden to obtain "sane" behaviours. Finally, it should be noted that there are many things in here which are just plain clunky to use.

So, how do these experiences actually tie into the original topic of this post, Blanchette's "The Little Manual of API Design"?

Well, it turns out that Blanchette is/was one of the architects of Qt, working at Trolltech to develop parts of the framework which were included in the Qt3 and Qt4 series. As stated in the introduction (and also again in a few places during the text), the examples included in this text were specifically based on lessons learnt and principles used/applied by this team of developers. Indeed, the use of concrete examples from the Qt API was IMO a really nice touch which really helped to ground and enforce the concepts presented, but also to gain a better appreciation for some of the "forces" and "tensions" that have helped shape a real life design. As they say, "the proof is in the pudding"... :)