Skip to main content
Enterprise Agile Planning Image

This post is from the CollabNet VersionOne blog and has not been updated since the original publish date.

Last Updated Jan 24, 2013 — Enterprise Agile Planning expert

Is API First Just Another Term for BDUF?

Enterprise Agile Planning
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.

More from the Blog

View more
Jul 27, 2021 Becomes First to Achieve FedRAMP Moderate “In Process” Status for Enterprise Agile Planning Solution

Enterprise Agile Planning, the leading AI-driven DevOps value stream delivery, and ma ...
Read More
Jun 21, 2021

How Agile can be implemented effectively across the organization

Enterprise Agile Planning
Just a few decades ago, a “disruption” was seen as an undesirable thin ...
Read More
May 31, 2021

Agile change management processes are key to delivering software faster

Enterprise Agile Planning
With its emphasis on delivery value faster, agile product management s ...
Read More
May 03, 2021

Bringing the agile planning approach to your whole business

Enterprise Agile Planning
The events of the last 12 months have demonstrated that the only sure ...
Read More
Contact Us