A 14-Point Framework for Evaluating Programming Libraries & APIs (Part 1)

Libraries, network-services, virtual machines, platforms and frameworks, all qualify under the umbrella term "API". Some are simply things to be lived with — if we develop Windows applications, if we write Android or iOS applications, then we're blessed or cursed with certain platform-level givens, and there's not a great deal we can do about them apart from, perhaps, wrapping them behind a facade layer that feels a bit "nicer" — that makes life a little easier for us as developers by providing abstractions that more closely match the abstractions defined in our own applications and hiding layers of complexity that must necessarily be handled, but are uninteresting or distracting from the goals for our own development.

Aside from those "givens" we are faced (almost daily) with choosing other utility libraries and services to make our own development faster, simpler, more reliable, more performant and less repetitive.

This then, brings us to the heart of my topic: What exactly is it that makes one programming interface "nicer" than another? What makes one library "better" than another? Is it the expressive power? How would we go about measuring that? Is it how quickly we can churn out useful code, working correctly? Does popularity and coolness matter? There has to be a better way to measure — if only in a fuzzy and inexact way — whether one library or REST service is better suited to our needs and wants than another, and whether using a particular library might be better or worse than writing our own.

In case it is not already clear, let me emphasize: There is no One True Best API for any given task. Every problem lives in a context — a set of forces pushing and pulling on the boundaries of the solution space, warping the texture of the implementation landscape. Costs, time, expertise and past experience, functional requirements, timing and reliability constraints and, not least, developers' penchant for playing with the newest, shiny technologies — their desire to learn and extend their mastery. So: each and every API we choose to employ (as opposed to those that are forced upon us whether we will or no) must be tested against the problems we are trying to solve and the constraints and forces acting upon us and our application. A particular library may be the "right" answer for one project, but be quite inappropriate for the next one. Our desire for "good architecture"[1] suggests that we should, at least, make those choices consciously and deliberately rather than blindly or reflexively.

In what follows, I suggest some ways we might pick apart the various dimensions we might choose to use in evaluating various competing APIs, identifying 14 dimensions that you might want to consider as evaluation metrics in choosing (or avoiding) an API.

I should emphasize that I consider APIs (along with programming languages, platforms and codebase-hygiene) as primarily a UX problem. These things are all first and foremost user-interfaces for us, as tool-manufacturing humans to use, misuse or abuse. The principal question is, "How likely is it that this tool (API) will lead us astray and into the murky swamp of technical-despair?" versus "To what degree will this tool allow us to write less code, more reliable code, more readable (comprehensible, therefore maintainable) code?"

[1] I refrain from trying to nail down just what constitutes "good architecture" and rely, here, on your own intuition and experience. Suffice to say that it extends well beyond the merely technical concerns and encompasses the human, social and business spheres, too.

1. Surface Area

How many types, methods, configuration items do you have to learn in order to use this thing?

This is not unrelated to the ideas of Function Points as a way to "size" software — it attempts to measure the number of inputs and outputs (since that's what types and configuration items are) and use-cases for those moving parts. The absolute number is not important, since different APIs address problems of many sizes and a wide range of complexity, but it can be useful in comparing APIs that purport to solve the same or similar problem-spaces.

2. Coverage

How much of the topic-area does an API address? Is that what you need?

Does the API do all that you expect it to do? Does it do way more than you need? If the API is functionally incomplete, you will find yourself writing supplementary code to make up its deficiencies. That may be acceptable, but it may spell trouble if the API in question is supposed to be solving some complex or difficult problem (e.g. crypto) but is not sufficiently complete.

The case where an API covers way more territory than we really need is a little more subtle. Given appropriate tooling (not always available in all toolchains or environments) this is not primarily a technical problem (of linking too much object code into an application codebase, resulting in codebase bloat) but a cognition problem. Every part of an API wants to put little hooks into our brains. They call out to us, crying, "Me, me. Pay attention to me!" and we truly cannot afford to give them that time or mental space. Take the Google Guava library (for Java.) I use it on almost every Java project I am part of. But I only make really heavy use of maybe two chunks of what it does — the Preconditions and some annotations (for adding contract-like guarantees to classes) and the Collections (particularly Immutable collections) classes. The rest of the library is mostly surplus cognitive baggage most of the time. I'd be better off with it being in a separate library to be pulled in only when truly needed. Indeed, I have seen projects that end up with as many as three separate definitions of methods like isNullOrEmpty(aString) and checkNotNull(anObject) simply because developers did not want to pull in all of the Guava library in the early stages of their project, then acquired another instance of those methods because some other third-party library made those definitions, and, at the end of the day, they ended up using the Guava library anyway for other reasons. What a mess.

3. Composability

How well does this API play with other libraries and tools?

If an API works in terms of platform-compatible types, it is much more likely to play well with other APIs. If it insists upon introducing and using only its own types, it will be much more difficult for us to force it to play well with the other libraries in our armory — we are sure to find ourselves writing endless boilerplate code converting between custom datatypes. And unit tests for that code. Or not, so hurting our code coverage metrics and creating emotions of despondency and discouragement because clearly we suck at doing The Right Stuff.

4. Modularity

How easily can we break this library into pieces so that we can use just the bits we need?

This is (again) about reducing cognitive load. Does a library allow us to just pick and choose the bits that suit us well, leaving the remainder strictly alone, or does it force us to schlepp in all sorts of sundry other parts of the library that do not touch on the problem we're solving. Some frameworks tend to be really bad at this.

5. Openness

How much is this API a black-box?

Can you tweak the under-the-hood stuff if when you need to without delving into the twisty, slippery innards of the implementation? This is simply the Open-Closed Principle in its essence.

6. Opacity

How well does an API hide the details and complexities of the problem-space? A well-thought-out API will shield us (to an appropriate degree) from the concepts and particularities of the underlying domain it deals with, allowing us to work with concepts the ought to be much closer to our own, more familiar application domain. The types and operations exposed at the surface of the API should reflect something more amenable to adaptation to our own conceptual framework than the underlying problem that it hides and manages.

If a library is not making stuff simpler for us, why bother using it? Does it provide a facade that makes sense in the context of the problem your application is attempting to solve?

7. Accessibility

Can you learn just a little bit of the library and be useful (Vertx), or do you need to learn the whole damn thing before you can (safely) use any of it? (Git)

Accessibility is one of the more important dimensions for thinking about APIs because it means we can tackle the (sometimes daunting) task of learning to use a library truly effectively in little bites, and each little bite that we can chew and swallow gives us an ever-increasing confidence in the library, and an ever-increasing confidence in our own abilities to put it to good use.

---

I shall continue with the remaining seven dimensions in a follow-up post in a couple of days. This thing is already too long for Internet-attention-spans as it is.

Extraordinary, Driven, Passionate, Imaginative, Remarkable, Phenomenal, Seasoned Developer Wanted. Apply within.

Recently spotted on the Internet:

Open Positions

• Extraordinary DevOps Leader
• Driven JavaScript / Node.js Developer
• Remarkable PHP Engineer
• Imaginative iOS Developer
• Passionate UX/UI Designer
• Seasoned Python Developer

(Really. I didn't make these up.)

---

I wondered if I'd qualify for any of those, if I have the necessary qualities, even supposing I possessed the requisite hard skills...

Extraordinary?

No, I don't think I am extraordinary. Most humans are not extraordinary. Most humans are pretty ordinary. That said, I've certainly done some unusual things. The most unusual was probably dropping out of my corporate programming and design job, with all its advantages of good income, city lifestyle and boringboringboringboring to live out in the sticks on a rural smallholding, trying to be self-sufficientish, growing my own food, supplying my own water, brewing my own beer, and learning. Always learning...

Driven?

Yes, I confess, I have been driven.

Back in late 1999 into 2000 I did a gig that involved me living and working in Switzerland for about six months, on and off. Not in Switzerland as much as in one particular Canton that has (I was told) specific IP treaties with various other parts of the world that were (I was told) essential to the success of The Venture.

I was accommodated in particularly upmarket lodgings -- an apartment in the same building that housed the offices and personal home-away-from-home of one of the Money Principals of the venture -- one of the 0.0001%. Lovely views of the lake, famous Alpine peaks visible in the distance, clouds permitting. I had some lingering contractual obligations back in Cape Town that required me to commute between Switzerland and SA every fortnight. Business Class, naturally, at the expense of The Venture. Man, I accumulated a lot of frequent-flier miles that way.

Each time I landed back in Zurich, The Venture's minions would arrange for a taxi to schlepp me from the airport to the office. And what a taxi. Not some grotty yellow clapper with slightly sticky seats and cigarette-infused upholstery, oh no! A Mercedes limo, all leather and walnut, and Herr Geissler's pidgin English offering to take me via the scenic route as I reclined in luxury in the back watching through the blacked-tinted windows as the chocolate-box chalets went whooshing by. The trip from airport to office took around forty minutes, unless we took the scenic route.

One time, though, something went wrong, and the minions failed to arrange for Herr Geissler. Some communication breakdown. By now quite familiar with the ins-and-outs of Swiss travel, I simply took the train. There's a station right beneath your feet at Kloten airport Terminal B. To my delight I discovered that, even with a change of trains at Zurich Hauptbahnhof, the trip took only twenty-two scenic minutes by rail and Swiss chronometer, and deposited me a pleasant, three-minute walk from the office. After that I took the train whenever I was given the choice. I never commuted with Herr Giessler again, except for one last, wild time. But that's subject matter for another story altogether.

So: Driven? Yes, I've been driven. And I prefer the train, thank you.

Passionate?

Yes, I sometimes get passionate with my wife... occasionally I've been tempted to get passionate with other people. It has generally not ended well.

The thing about Passion is that it's all hot-bloodedness, sweaty palms, thumping heart, furious emotion and throbbing other bits. And bloody short-lived. Is that really what you're looking for in an Android Developer? Or would you rather hire someone who will see the project through the inevitable rough patches where your client suddenly and unreasonably invokes the corporate lawyers' jotts and tittles and throws a cast-iron spike through the limpid clarity of your gifted UX designer's heaven-inspiring vision, rewriting the spec into something dreamed up by the by-blow offspring of Dante Alighieri and H P Lovecroft on bad acid after a hard night jamming black-metal and burning Norwegian churches?

If that's really the sort of Passion you're looking for, I think I'll pass.

Imaginative?

Is there a single human-being on this Earth, of average intelligence or better, who is not imaginative? Just watch a small child persuading its parents that, No, I am NOT tired, I do NOT need to go to bed just now. Hell, even my dogs are imaginative when they're trying to persuade me to take them for a walk.

Then, too, I have been known to make claims of being a Writer (I don't say Published) of Science Fiction stories. That certainly takes some imagination. But then I had lots of practice. I learned from a Master. I went to a really strict Boys' High School, you see, along with my best mate, Roy. And Roy was one of the Naughty Boys. Constantly getting into trouble with the powers that were. More than half the time it was not even his fault and he was merely the unwitting victim of circumstance. He had some sort of genetic predisposition towards attracting trouble to himself. Consequently he became a Master at Talking His Way Out Of Trouble, and, along the way, I learned a whole lot from him about the art of fabricating stories. I learned, too, that the stories often don't need to be particularly plausible. Just good enough for the people who want to be able to pretend to believe. And that's all it takes for Science Fiction.

So: Imaginative? Yes, I think I'll own that one.

Remarkable?

I am never quite sure of the word "remarkable". Does it mean that I've done something that other people find odd enough to want to remark on, or does it mean that I am "able" to make "remarks" about odd stuff, thus being remark-able? I suspect (duh) that when you say you're looking for a Remarkable Engineer you mean the first sense -- you want someone who is "remark"-worthy. The trouble is that you don't say what they should be remarkable for... is it their dress-sense, the oddly clashing colours, pink shirt and purple neckscarf topping olive drab pants rolled up to the knees that they think make some sort of declaration of disdain for the world of conventional fashion and the sheer quantity of metalwork rivetted through the flesh of one ear so as to cause their head to lean markedly to one side? I'd certainly remark on that.

Not that I'm pointing a finger, mind. Not me. Very tolerant, I am. Peoples lifestyle and dress choices are their own, and frequently the least interesting thing about them. After all, it is pretty certain that I do or have done some things in my time that might give other people cause to remark on me. Like the sleeveless Afghan goatskin I affected back in the earliest of my student days. At least until the blackened pinhole burns multiplied like some ebonite ur-acne. That was probably remarkable. At least, the smell probably was.

So: Remarkable? Yeah, I'll 'fess up to that one, too.

Phenomenal?

Well, "phenomenal" is the adjectival form of "phenomenon", which one dictionary defines as "an appearance or immediate object of awareness in experience; a thing as it appears to and is constructed by the mind, as distinguished from a noumenon, or thing-in-itself."

I have long held the theory that the practice of software development (writing programs, to be less pretentious) is exactly the Practice of Magic. I mean, look at the Sorcerers and Wizards of fable and fantasy. (It is entirely Terry Pratchett's fault that I always want to spell Wizard with two Zs.) No, seriously, I am not even joking, here. The Sorcerers and/or Wizards (delete where not applicable) confine themselves to smoky dungeons/high garrets/dark towers, surrounded by piled-high stacks of grimoires, crafting intricate and eldritch spells in arcane and incomprehensible languages. Enchantments that, upon release into the world, wreak havoc, mayhem and general confusion. (I believe we call it "Disrupting Entrenched Monopolies".)

Remind me again: What's the difference between programming and sorcery? And Javascript really is pretty cryptic and arcane, isn't it. I wonder what DevOps opportunities there might be at Hogwarts, and do they do Agile at Mordor. (I doubt it.)

So I contend that software is all "a thing as it appears to and is constructed by the mind". By that measure, then, all software is Phenomenal. So, in using the word "phenomenal" in relation to writing code, you said nothing at all.

Seasoned?

Seasoned? What does that even mean -- a "seasoned" developer? That I've been left out in the Sun too long? That I smell a bit ripe? I don't want to know.

I can chuck some salt and pepper over myself if you like. Chilli flakes, even. MSG. Is that seasoned enough?

Finally?

Finally!

While it was not specific to any of the positions you advertised, in puffing up your dev group you invite me to "work with an absurdly talented group of people..."

I think I'll join the circus then. The Bearded Lady. The Dancing Bear. The Siamese Kittens. The Sword Swallower and the Tattooed Map Lady whose Ass Can Be Seen From Her Elba. Absurd and talented, all. Maybe they need a Scrum Master...

Turning URLs into URIs: shrtn - A URL redirector/shortener.

The shutting down by Google of their project-hosting has forced me to migrate my URL-shortener project to BitBucket (because Mercurial is so much nicer than GIT), and along the way caused me to take it upon myself to resuscitate the project. For one thing, I've passed out URLS that rely on it residing at 1.mikro2nd.net, and, as things currently stand, those are dead links. For another, I've figured out a second, more important, use case for URL redirectors than mere shortening. 

While shortening URLS may have some (highly debatable) utility, I consider them to be, on balance, a harmful thing. They make the link destination opaque, and the poor sucker clicking on them has absolutely no idea where they might end up. Then, too, the indirection allows the redirector host to potential introduce any sorts of mischief or stupidity into the user's browse path. These are not insurmountable problems, just small stumbling blocks in the path of the concept, but they do argue for considering URL-shortening to be harmful. Or at least seldom accruing benefit to the clicker.

What they do buy you is the ability to gather ego-gratifying statistics on who clicked your links, which can give you a measure of how well your voice is heard in the social Internet. An oft misleading measure, to be sure, but sometimes some measure is better than none, as long as the user of said statistics remains aware of their limitations and biases.

There is, though, a very legitimate and compelling use for the idea of redirectors: They provide a bridge between the world of URIs and the world of URLs. (For the longest time I was a bit hazy on the distinction between the two, but I'm better, now, thank you.) A shortener (or redirector) service allows us to publish identifiers of stuff (I'm trying to avoid the "content" word having developed a nasty allergy) to the 'net without worrying about the location or address of that stuff. For example, I might have published a document (or an application or a collection of photographs or whatever) using some file-hosting service. Let's call it odearieme.com. Now it turns out that odearieme.com was also hosting a bunch of stuff that the American copyright fascists decide they want disappeared. So they have the FBI kick down the doors of ohdearieme's hosting centre with the aid of a compliant country's spook services, and they steal remove the servers holding your perfectly legitimate and legal "stuff". Too bad. Anybody hanging on to the URL you gave them referring to ohdearieme.com is now stock out of luck. Had you used a redirector, though, it would be no problem. All you'd have to do is upload a copy of your "stuff" to a new file hosting service ad change the destination URL in you redirector. This is, indeed, as useful thing, and, after all, exactly what they Domain Name System is all about.

So there's my compelling use-case for a URL shortener/redirector, and I still have a couple of hundred words to write to reach my day's target. Let me describe, then, some of my other thinking around this little project.

I've already implemented two or three different storage schemes for the "database" that the server needs in order to work, and exactly which one gets used for a given deployment is merely a configuration issue. So what's another one? The trouble is that it is becoming cumbersome to include all the storage implementations, along with their dependencies, in the final deployed product. I know that many, if not most, developers would just chuck everything and the bathtub into the deployment, but it offends my sense of neatness. I want to build a number of separate artefacts: one that contains the actual redirector server, and then one for each storage scheme. That way a deployer (or, heavens forfend, an actual System Administrator) can deploy only the exact artefacts they need. This also means that updates to one module don't necessitate a refresh of the entire system. More immediately, it means that I want to build a number of separate artefacts for this project, rather than a simple WAR file, making Maven a much better fit than the straightforward Ant build generated by Netbeans, so I'm having to (at last) learn something about using Maven properly. I guess I'll learn to live with the tediously slow builds, though it does feel like the 1990's called and want their Makefiles back.

Then, too, I'm of a mind to host this thing (at least my own personal redirector) on Google's massive cloudy infrastructure. Given the meagre volumes of data I'll be shifting (which, presumably, speaks volumes for the paucity of my Social Internet Fu) I'm pretty-well certain I can keep hosting it there free for all eternity—or until Google decide to shut down their cloudy hosting engines or make them for-pay only. If or when that happens I guess I'll have to move the redirector back onto my own infrastructure, so I don't want to lose the ability to deploy to my own (Tomcat) application server. That means teasing out the deployment configuration and infrastructure-specific stuff from the core of the redirector code itself. All sounds reasonably doable for me, and I'm using the exercise to polish up my Mercurial, Maven and AppEngine skills, not to mention brushing up on changes in the Java language and APIs. I might even use it to improve my Javascript skills or get properly to grips with one of the JS front-end frameworks.