Skip to main content
Enterprise Agile Planning icon with arrows

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 Government Cloud
Apr 12, 2022 Government Cloud receives FedRAMP Authorization through sponsorship from the United States Department of Veterans Affairs

Enterprise Agile Planning
Flagship Agility solutions can effectively scale agile deve ...
Read More
Nov 22, 2021

What are the qualities of highly effective agile teams?

Enterprise Agile Planning
A team is the core unit of productivity in an agile organization. Wher ...
Read More
Nov 15, 2021

How an open-first attitude revolutionized government tech development

Enterprise Agile Planning
Public perception of government is often that it is slow-moving, reluc ...
Read More
cross functional
Nov 08, 2021

6 best practices for building resilient cross-functional teams

Enterprise Agile Planning
Agile frameworks prize the quality of resilience within every facet of ...
Read More
Contact Us