Facilitating the Spread of Knowledge and Innovation in Professional Software Development

Write for InfoQ


Choose your language

InfoQ Homepage News API Design-First Using the "Align-Define-Design-Refine" Process

API Design-First Using the "Align-Define-Design-Refine" Process

This item in japanese

Lire ce contenu en français


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”.

Rate this Article


Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Community comments

  • Good old contract-first design approach

    by Paulo Merson,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    The ADDR process gives developers a method to apply the good old contract-first design precept, which has been recommended since the SOA days in the 2000s. Contract-first (or API design-first) is particularly important for public APIs.
    The article points out the benefits of the approach to create long-lasting APIs. The main challenge is the initial overhead to design the API, which is increased if you don't have API design standards in place.

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p