Home > Development, Rants > API Design

API Design

December 28th, 2005 Leave a comment Go to comments

Winter must just affect people in a certain way – for some reason, I can’t seem to open up my blog reader without running into two or three articles on API design. Now, I’ll admit, I’ve seen some pretty poor APIs in my day (I still cringe when I think of the classes I’ve dealt with that had a singleton method) but it’s quite interesting that there has been so much chatter on this topic of late. I’m sure some of it is cross contamination – chances are the people I’m reading are also reading each other (in a nutshell, that’s what the collaborative filtering concept is all about – the notion that similar people like similar things). Or maybe short (cold) days just force people to sit in front of their computers more (my notebook is quite warm).

Anyway, I just thought it would be of value to my reader to point out some of the recent news on API design. Near as I can tell, Martin Fowler kicked this all off with a piece titled Humane Interface in early December. Ironically, I was helping a coworker with a validation service just after I read this and it did influence my advice. I’m somewhat torn on Fowler’s assertions here – on the one hand a small interface can be easier to learn however, a more explicit (though larger) interface can actually be easier to use. Like so many things, your users will let you know though I think it’s key to remember there is a big difference between writing a framework like API that will be used by lots and lots of developers (that are outside of your purview) and good design for APIs that are used within an application. And this distinction explains some of my disagreements with Eamonn McManusJava API Design Guidelines piece.

In general, I like Eamonn’s article. He hits it right on the head when he says design to evolve and his quotes of Bloch’s Effective Java are spot on. I was also pleased to see that he touched on ease of use and easy to learn – too many APIs are clearly not designed for regular old developers. Sure, they might make sense to Stanford PhD candidates but to those of use without Ivy League (and yes, I know that Stanford isn’t an Ivy League school…) educations, they are a bit obtuse (see we can use big words too – though I will admit I really like OS X’s built in dictionary – to the point where I get irritated that my work machine is XP). Still, I couldn’t help but think that Eamonn approaches this topic from the standpoint of framework designer (in this case someone that works on the Java specs). For instance, I’m not so sure I agree completely with his assertion concerning backward compatibility. Sure, you can’t just remove a public method in a superclass (twice…in a week) without checking with the rest of the team but if we never remove anything, why even have the concept of deprecation?

Good old Mr. Fowler wasn’t quite done on the topic of APIs. First, you should check out all the responses that Martin’s Humane Interface entry caused (scroll down). Of course the opposite school of thought is Minimal Interface! Honestly, I think I’m leaning towards larger interfaces but maybe it’s just because the days are getting longer. Ask me again next fall. More recently, Martin added another entry: Fluent Interface. I’m really intrigued by this approach though it seems like a Fluent Interface really only makes sense in context – in other words, the methods by themselves aren’t so obvious. I’m not sure where this falls on the ease of use/easy to learn scale but I do wonder if newbies would have a hard time getting up to speed on a application that made wide use of Fluent Interfaces. Of course maybe they only make sense in concentrated doses.

But he’s not done yet! Oh no, he’s practically the Energizer Bunny of API articles. Just last week, Martin posted an entry on Duck Interfaces. In general, I find dynamic languages can be easier to work with especially when I think of all the casting I’ve done in Java over the years. Seriously I put the objects in the collection, I know what type they are…again it’s the difference between writing a framework vs. writing an application. If I’m writing a framework that you are going to use, by rule I have to distrust you and write more defensively. Of course if I control the code I can be less wary. I’m also reminded of a comment Dave Thomas made concerning dynamically typed languages: when was the last time you got a class cast on a deployed app? Why didn’t you catch it in testing?

I’m sure there are oodles of other articles out there but this small subset caught my attention – enough so that I actually took the time to sit down and write this up. Of course I could also just be procrastinating on my latest project…

Categories: Development, Rants Tags:
  1. No comments yet.
  1. No trackbacks yet.