Back in 2005, Erich Gamma and John Wiegand described the Eclipse Way, the set of inter-related practices that enabled the success of the Eclipse community. At the time, anyone looking at the process would have immediately recognized it as agile: regular customer (community) involvement, incremental planning, short development cycles, and continuous testing and integration. On the other hand, the Eclipse Way embraces the practice called API First, which, to some ears, sounds a little too much like big design up-front (BDUF).
The difficulty of APIs is the tension between the need for evolution and the need for stability. Evolution is necessary because the best designs are emergent. It takes iteration and incremental implementation to get a design “right.” On the other hand, stability is just as important for adoption as being “right.” Few developers can manage to build with an API that is changing rapidly. The practice of API First is an approach to resolving this tension. To promote evolution, API First tells us “always have a client.” This drives YAGNI thinking and validates the design. To promote stability, API First tells us “ship no API before its time.” This sets clear expectations that early APIs need room to change, while time-proven APIs should be dependable and reliable.
The language of API First that may be most objectionable is the notion of “specifications.” Gamma/Wiegand say that APIs need “specifications with precisely defined behavior.” Rivieres says “write comprehensive API specs.” At first glance, both phrases may seem very much like BDUF and defies the agile value of “working software over comprehensive documentation.” However, the interpretation at Eclipse is eminently practical. What these phrases usually mean is providing ample Javadocs so the packages and interfaces have human readable documentation. The validation of “precise” or “comprehensive” is that other people can build on those APIs by reading the documentation. Since API First was first described in 2005, the practices and tooling for Specification by Example have matured considerably, meaning specifications can be both human readable and drive automated tests. Further blurring the lines between documentation and executable are web tools like Swagger. Instead of out-of-date prose and disconnected diagrams found in documentation, specifications can be a living part of working software.
Fundamentally, API First elaborates on two agile principles: (1) “Continuous attention to technical excellence and good design enhances agility,” and (2) “The best architectures, requirements, and designs emerge from self-organizing teams.” Although API First was shaped by experience in the Java world, it remains relevant for any product that has distributed development.