Designing APIs that Stand the Test of Time

Programmer Interface (API)-design business to learn from their mistakes - usually without any formal background or training on the subject. The subject of API design is remarkable for its lack of available training or established best practices. This paper should be immediately applicable to authors using any single-inheritance object-oriented language, with useful ideas applicable to multiple-inheritance and non-object-oriented languages as well. We offer the fruits of eight years of hard lessons in practical design of public APIs in the Java language - including the experience of having made some of the worst mistakes one can make in designing public APIs and recovering from them, wherever possible, compatibly. We particularly focus on how to design public APIs such that they meet the needs of (and are comprehensible to) the consumers of libraries while preserving as much freedom as possible for the API author to evolve the API in a binary-, and where possible, source-compatible way over time. In layman's terms, this paper is about how to avoid painting yourself into a corner when designing an API, while enhancing, rather than compromising, the usability of the result. We will cover API design patterns and anti-patterns, provide a working definition of source- and binary-backward-compatibility, and provide practical case histories of successes and failures and examples of our current practices to avoid future failures.