The API consultant James Higginbotham wrote recently about the advantages of adopting an API design-first approach using the “Align-Define-Design-Refine” (ADDR) process. ADDR is an iterative process meant to guide its adopters through such API design-first techniques. Designing an API iteratively while ensuring that all stakeholders are actively involved is essential to agility in development.
According to the author, an API design-first process happens before writing any production code. It consists of translating the business requirements into an API design that delivers the desired results. The goal is to obtain sufficient details beforehand to prevent breaking changes in the future while allowing API clients to integrate it without waiting for full implementation. Teams are enabled to “move quickly, thoughtfully, and with the agility to make changes early in the process”.
Higginbotham argues that an API design process “encourages efficiency throughout the delivery process”. This effect occurs because the primary focus is the API contract and the needs of users and developers. Resiliency to internal implementation changes over time is a benefit of API design processes.
The author’s ADDR process divides the API design-first process into cycles comprised of seven steps grouped into four phases. These phases are Align, Define, Design and Refine.
The idea is to align all stakeholders, then map their requirements into digital capability definitions, resulting in a technical API design. This design is then refined through feedback, documentation, prototyping and testing. Since ADDR is an iterative process, the learnings from each iteration are taken as inputs to the next.
The author points out that the design of an API is a separate and critical step of software delivery while at the same time recognising that teams can design and deliver APIs successfully without following a formal design process.
Other authors have expressed their views about API design. They tend to converge on the same conclusions.
Joshua Bloch, professor at Carnegie Mellon University, wrote an article about API design on InfoQ. There, he lists many principles of API design and agrees that requirement gathering needs to be the first step in the process. These requirements should then be structured as use-cases and finally coded against the API before it is implemented.
The first point of Ronnie Mitra, director of technology at Publicis Sapient, in his API design process article on InfoQ is that “good API design happens in iterations”.
Higginbotham details his ADDR process in his upcoming book, “Principles of Web API Design: Delivering Value with APIs and Microservices”.