API Lessons

A co-worker came by my desk at work today to ask a question about a software component that I had been involved in designing and implementing. The more that we talked, the more his questions turned into complaining about the component design... primarily it's API. Now this kind of bothered me at the time, but the more I thought about it the more I came to realize that he was right - and I think that I know why.

While I haven't been directly involved in maintaining that particular component, I can still remember the project quite well. It was a relatively small project to design an infrastructure utility that could be re-used by various larger applications. There was no user interface (graphical or command-line) - just a bunch of Java classes that were bundled as a jar file for other development teams to use when they needed this certain functionality. I think that part of the problem was that without that standard user interface, we ended forgetting that our product still had a customer: other developers within the organization.

While there are lots of important things to remember when designing and building software, there are a couple of items that I think deserve extra emphasis when writing a component with a programming API - and writing them down now will help me remember them next time:

Don't wait until the internal design is complete before designing your API.
You will end up with an API that is far too tightly coupled to your internal design (can anyone say Leaky Abstraction?). Looking back now, I realize that during all of those weeks of design and development, we never once had a discussion on *how* the "customer" was going to use our beautifully designed piece of software. Of course we all knew that there would need to be an API for our component (we weren't completely clueless). It was shown as a nice thin layer on our architecture diagrams. But no one actually designed that API until the implementation was partially complete. I use the term "design" quite loosely here, because I honestly don't know how the API came to be, it just kind of appeared in our source code repository somewhere along the way.

USE your API before it's final release.
Write a sample application, or some extended functional tests - whatever. If you use it before you release it, then there is still time for change those pieces that looked good on paper, but don't really work in the real world. I am ashamed to admit that to this day, I have still never written any code (other than some isolated unit tests) that actually used the component that I helped to build. As far as I'm concerned, that's the equivalent of writing a web site in a text editor and never actually loading it into the browser and clicking your way through!

So, whether you are writing a more traditional application with a user interface, or a more technical component like a programming library - don't forget about your customer.

Oh yeah - it wouldn't hurt to read up a bit on API design before starting, like these slides (pdf) from Joshua Bloch.