The Little Manual of API Design
📜 Abstract
This manual gathers together the key insights into API design that were discovered through many years of software development on the Qt application development framework at Trolltech (now part of Nokia). When designing and implementing a library, you should also keep other factors in mind, such as efficiency and ease of implementation, in addition to pure API considerations. And although the focus is on public APIs, there is no harm in applying the principles described here when writing application code or internal library code.
✨ Summary
Overview
The manual presents API design as the design of abstractions through which other programmers build applications. It argues that API quality should be judged primarily by whether an interface is easy to learn and remember, leads to readable code, is difficult to misuse, can be extended, and is sufficiently complete. Minimality and consistency are treated as means to these goals rather than independent objectives.
The recommended design process is user- and example-driven. Designers should first understand requirements, write representative use cases, inspect analogous APIs in the same library, define semantics before implementation, obtain peer feedback, and test the proposed interface through multiple examples. The manual emphasizes that implementation details should not dictate the public API, because APIs commonly outlive their implementations. It also recommends planning for both maintainer- and user-driven extensions, reviewing internal interfaces before publication, and deferring questionable functionality until there is stronger evidence that it is needed.
The design guidelines focus on clear naming, unambiguous terminology, meaningful parameter names, avoidance of unnecessary abbreviations, specific rather than overly general names, and independence from poorly designed underlying APIs. Semantically, the manual advocates useful defaults, predictable behavior, limited hidden side effects, careful treatment of edge cases, and deliberate decisions about virtual methods. Structurally, it favors property-based interfaces when objects have many optional attributes, since properties improve readability, reduce ordering errors, support defaults, and allow later modification. Its final principle is that the best API may be the one that eliminates the need for application code altogether.
Evidence of influence
The manual has been used as a reference in subsequent API-usability research, including a study of structural measures for API usability, where it appears alongside work on API evolution and usability evaluation. (onlinelibrary.wiley.com) It has also been cited in later academic and technical design work, including a thesis on declarative visualization APIs and studies of API usability and string-library design. (pm.inf.ethz.ch)
There is documented industry uptake as well: Goldman Sachs identified the manual as a resource for redesigning component APIs in its UI Toolkit and reported applying its principles during that transformation. (developer.gs.com) The manual is also included in API-design guidance and educational materials, including the PCL API consideration guide and university software-design curricula. (pcl.readthedocs.io) These sources demonstrate continued citation and practical use, but do not establish that the manual alone caused the reported design changes.