Progressive Disclosure in API Design with example

You have probably heard about the progressive disclosure principle of UI design. In Progressive disclosure design you defer advanced or rarely used features to a secondary screen, making applications easier to learn and less error-prone. It has been successfully argued that the same principles can be and should be applied to API design, which are consumed by humans (programmers).

Jacob Nielsen famously described Progressive Disclosure in 2006:

Interaction designers face a dilemma:

• Users want power, features, and enough options to handle all of their special needs. (Everybody is a special case somehow. For example: Who wants line numbers in a word processor? Millions of users, that’s who, including most big law firms.)
• Users want simplicity; they don’t have time learn a profusion of features in enough depth to select the few that are optimal for their needs.

Progressive disclosure is one of the best ways to satisfy both of these conflicting requirements. It’s a simple, yet powerful idea:

1. Initially, show users only a few of the most important options.
2. Offer a larger set of specialized options upon request. Disclose these secondary features only if a user asks for them, meaning that most users can proceed with their tasks without worrying about this added complexity.

Ken Arnold in his article Programmers Are People too, explained Progressive Disclosure as applied to API design with a great example from Swing API, which is dauntingly complex with its vast array of infrequently used methods.

We could do the same thing with APIs. For example, the Java Swing JButton class—the basic GUI button—has well over 100 methods. But if you think about GUI buttons, there are only a half-dozen things you typically care about most of the time. When presented with this massive complexity, how are you to tell where to start? Should you be adjusting the preferred or minimum size? What happens if you change the text? Do you need to fire those things called “change listeners,” and if so, which kind?

To start getting this nonsense under control, you can start by breaking the JButton methods down into three major groups:

• The basic methods needed by most of us (set text/icon, add a callback listener for when the button is pressed).
• The expert methods for folks who want to get in and tweak (the font, color, border style).
• The integration methods needed by folks who write GUI widgets in Swing, who are a very rare breed of programmer (sizes, firing off change listeners, re-parenting).

Now we could use progressive disclosure to help reduce the complexity of that JButton class: put the expert stuff in an object returned by a getExpertKnobs() method, and the graphics subsystem hooks in an object returned by a getIntegrationHooks() method, and you would be left with a button API that had just a handful of methods—the basic methods we all need.

Db4o API is implements this paradigm perfectly in several places. The basic ObjectServer, for example comes only with methods to grant access, open or close a client. It provides an ext() method which provides access to ExtObjectServer, with less frequently used methods. In previous versions Db4o object (still available but with mostly deprecated methods) similarly provided access to ExtDb4o object for extended features. This particular design of Db40 dramatically reduces the learning curve and makes it a pleasure to use in my experience.

To know more about Db4o read our guide to learning Db4o, Java Object Database, in under 5 minutes. Also look into couple of tricks and gotchas with Db4o.

One of the major challenge of Java API and its lack of even more wider adoption is its inability to reduce complexity for newcomers. Any developer is likely to be overwhelmed by the wide array of Java methods in any single class.