API Design I — Beyond Contract and Correctness
An API (Application Programming Interface) exists for interfacing a given software system with other software systems. The interface or bridge, allows the external world to interact with the internal world of the software system in a limited, controlled manner.
In bridging the two worlds, like a translator, the API designer has to be aware of concepts prevalent in both the worlds. If the differences between the two worlds are non-trivial, the API may need to introduce additional abstractions — even new levels of indirection, in fact, a whole new layer. For example, a file system API creates metaphor of traditional paper-based office metaphor of cabinets, folders, documents (files) and trash. In the process, it hides implementation details of interfacing with the storage medium — usually disk with tracks and sectors.
A metaphor itself is a device connecting two worlds — using a familiar concept in one world to introduce an unfamiliar concept from another world. Metaphors are favorite technique of communicators — especially educators.
However, programmers do not think of themselves as communicators or educators. User interface designers do. Jennifer Tidwell in Designing Interfaces : Patterns for Effective Interaction Design encourages designers to ask this fundamental question: –
How much effort are your users willing to spend to learn your interface?
The same questions an API designer should be asking for making life easier for the users of the API.
Once you start pondering the question, the previous post –Passing an elephant through the eye of a needle — becomes relevant.
Most programmers though, view API design more in terms of establishing a contract. In fact, most programmers think of ‘interface’ as a contract between implementation and the consumer. They imagine a single world, where everyone understands everyone else. And so usually, they are preoccupied with focus more on efficiency, performance and almost never speak of ease of use.
Instead, for all non-trivial systems, an API designer should be sensitive to users of the API, just like the user interface designer. Understand mental models of those users. Introduce intermediate abstractions, use relevant metaphors — think about ‘Gentle Introduction’.
