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
Apr 08, 2021

Making IT services more agile

Enterprise Agile Planning
The agile revolution completely transformed how we create digital prod ...
Read More
Feb 14, 2021

Reflecting on the 20th anniversary of the Agile Manifesto

Enterprise Agile Planning
Over the past 20 years, it’s been amazing to watch an idea from ...
Read More
Feb 08, 2021

How does agile apply to an entire organization?

Enterprise Agile Planning
Before we dive into the main subject of this blog post, it is importan ...
Read More
Feb 03, 2021

It took a pandemic to realize why digital transformation actually matters

Enterprise Agile Planning
Before anyone had ever heard of COVID-19, businesses across the globe ...
Read More
Contact Us