What I want From an API

A component’s API is critical to its success. A good component with a bad API is a bad component. It is the users of an API that decide whether it is a good API or a bad API.

A good API is an API that makes my life easy. Four ways that an API can make my life easy are:

1. Simplicity. I want as few classes in the API as is reasonable, with as few methods on each as is reasonable. Small APIs are good—because there is less to learn—but I’d rather have a few extra classes if that makes the API as a whole simpler.

2. Documentation. I want to know what each class and method does. I want to know when and how it fails and what it does if I pass null or some other invalid argument. I also want to know how the component interacts with its environment in response to my calls.

3. What not How. 99% of the time, I don’t care how the internals of a component I am using work. Really, I just don’t. Therefore, the interface should reflect what the component does, not how it does it.

Your report generator component uses XML internally? Fine. But don’t give me an API that looks like an XML parse tree. Especially not if you’re going to mark half the methods “for internal use only”. Sheesh.

4. Compact Usage. The fewer lines of code it takes to make a component do what I want, the better, so long as the resulting code is still understandable. For instance, here is a method I have re-written for nearly every Java project I have worked on:

public static Properties loadProperties(String name) 

            throws IOException {

    InputStream is = getClass()

            .getResourceAsStream(name);

    Properties p = new Properties();

    p.load(inputStream);

    return p;

}

Why do I have to write those six lines over and over again? An API designed for compact usage would include an additional factory method on Properties so that I could write:

    Properties p = Properties.loadResource(name);

In summary, there are many parallels between building good GUIs and building good APIs. Practice helps, as do writing out use cases and prototyping the interface. In the end it comes down to the same hard truths—some programmers can build good APIs, and some programmers can’t. And every single one of us likes to think that he can.