Having spent a bit of time thinking about developing APIs since the HP acquisition took place a few weeks ago, I was very amused by an ACM Queue piece, "APIs with an Appetite," which considers how APIs can get too fat too quickly.
In essence the piece argues that a well thought-out API will have just enough method calls to provide the intended functionality plus an "escape hatch" call which may be ugly but which plays a critical role. The example given is the UNIX file-access API with its 5 basic types of calls: open, close, write, read, and ioctl, the last being the escape hatch call which lets one pass almost any data structure down in the guts of the operating system and get almost anything back.
I've always thought of ioctl as the ugly stepchild which somehow broke with the elegance of the "stream of bites" abstraction of its four siblings. And yet, as the article argues, it is precisely ioctl's ugliness that allowed the rest of the API to remain so pure while still actually being useful.
It's interesting to consider this design approach in the newly emerging set of web service APIs. The Flickr API is the posterchild for the new web and yet, while the API is quite useful, the author of the ACM piece may consider it "fat." After all, there are a bunch of repeated methods for dealing with collections of things: photos, people, sets, etc. And yet, each of the method families belongs to a different namespace and returns slightly different data structures.
This short piece is definitely worth reading for anyone working on web service APIs. The final point about monitoring the use of the escape hatch call and learning from it how to evolve the API is perhaps most applicable in the web environment (where everything is centrally logged for later study). As the coolness of just having an API fades and is replaced with an explosion of services and APIs, we'd be well served to take this piece to heart.