Long time no see! It’s been a while since my last posting in the Shakespeare language. Perhaps my good friend OsQar will forgive me, though; this is not Middle English —just an international English. Fit and understandable for non-native speakers, laughable for oxfordians & cantabridgians alike. So there. And without more ado…

An API Metaphor

Since the inception of modern computer languages, an API has come to be closely associated with the concept of library. The object-oriented paradigm shift further specified the interface idea, sticking APIs with encapsulation in developers’ hive mind. But, alas, this is an utter, complete falsehood. As in ‘not true’. Please, go on reading before condemning me and all my bits for heresy or stupidity.

What is an API, then? Sure enough, Shakespeare did not have to address that concern in his plays. Not even was he conscious in the least what a bloody API was, by that matter. And yet, he used them all the time: there is certain abstract structure in a play that its ‘users’ have come to expect: acts, dialogs, author indications, dramatis personæ and so forth.

Encapsulation is fully orthogonal to an API, or else you should not be able to quote Shakespeare at all, since you would be unduly exposing inner functionality. How dangerous could that be? You would not be allowed to say

Let us sit upon the ground and tell sad stories of the death of kings.

Instead, you’d had to resort to some contorted reference, like

William Shakespeare (1564-1616), Richard II, Act 3, Scene 2, 22, 12-13.

By the way, all the Shakespeare I know I learned from Star Trek VI. So lame… I know. But let’s reinstate the vexing question: what is an API? In my generalization-prone mind, an API is…

Any publicly interoperable aspect of a system A, allowing a separate system B to invoke some functionality on A.

Not very restrictive, indeed. One may consider HCIs as a particular kind of API. And by ‘one’ and ‘may’ I really mean ‘I’ and ‘do’.

APIs and Web Applications

A web page may involuntarily expose an API to its users. Since the dawn of browsing (read: a little while after time began on 1/1/1970) people has tugged along with apps built upon third party web content, mostly web scrapers and such beasts. I know for sure because I witnessed one of the many ultimately doomed efforts in those golden times (anybody remembers Civista?) However, web scraping depends, ultimately, on a visual representation: yesteryear’s XPath implementations weren’t really mean for presentational markup, AKA tag soup, nor are today’s. Beware! Regex Hell awaits just a step away. Just imagine having to call methods on a Java library by regular expressions to understand the kind of punishment those poor souls had to endure.

Semantic web may have been too much of nothing for you people, but at least today the push for non-presentational markup is clear in the form of interoperability requirements. All of a sudden, XPath just works, and it can perform its magic even from a tiny bookmarklet. More advanced selection abilities are available to Javascript libraries like JQuery. Greasemonkey, discussed here in the past, allows the client side to interface with web applications. So, for all practical aspects, web pages are already exposing an API. Just a rather complex and disorganized one; but an API nevertheless.

Because APIs Happen

The wider audience a web app gets, the most probable is someone is interfacing to it rather than simply using it. A geeky concurrence also helps a tad. That’s why I’d like to introduce a new design constraint for web architects:

Try to embed a clear structure in your pages, and stick to it. That’s your published API. Treat it with respect.

A judicious use of class attributes would really go a long way. Say you’re implementing a toolbar, using a list as a semantic base (who wouldn’t?). You’re naturally going to style it with some gee-whiz CSS, aren’t you? Think carefully before altering that structure, or simply changing those class names: you may be pissing off your users. Those most advanced, and therefore influential users. Your API users.

That’s one of the truths of life: being an API maintainer sucks.