Overview of the ADDR API First Design Process

The Align-Define-Design-Refine (ADDR) Process is a lightweight approach that guides organization through an API design process in a repeatable way.

Why you need an API design process

An API design process helps your team:

  • Focus your API on delivering outcomes, not just raw data
  • Improve efficiency of communication across internal teams, partners, and customers
  • Encourage predictability in your delivery processes
  • Drive collaboration across teams through a teachable, repeatable approach
  • Track team process throughout the design process by reviewing the artifacts created along the way
  • Reduce implementation “leaks” into your API design

More details about why an API design process is important may be found in Chapter 1 of the book.

Overview of the ADDR process

The process is comprised of four phases:

  • Align Phase: Gain alignment of understanding and scope across business, product, and technology around a set of desired outcomes and the steps required to achieve those outcomes
  • Define Phase: Map the activity steps into one or more API profiles that describe the APIs and how they will deliver on the desired outcomes
  • Design Phase: Transform the API profiles into using one or more API styles including REST, GraphQL, and gRPC
  • Refine Phase: Incorporate fast feedback to improve the API design through the use of documentation, prototyping, and testing efforts

Each phase recommends one or two design activities to guide the process.

The diagram below illustrates the steps that make up the ADDR process:

Once the majority of the work across the phases have been completed, the delivery and management of the API takes over. Of course, the design may still be refined throughout the delivery process based on feedback or other non-functional requirements (e.g. performance requirements to meet established SLAs).

How does ADDR fit with an agile process?The ADDR process is designed to be used with an agile process. The most common approach is to focus first on the detailed Align and Define Phases to establish a clear definition of the outcomes and APIs required.

Then, iterate on the Design and Refine Phases over time to deliver the API iteratively. As learnings are gained along the way, the process may be revisited to improve the APIs and re-prioritize the roadmap.

Benefits of the ADDR process

There are several benefits to adopting the ADDR process:

  • Aligns business and technology by applying product thinking - Successful API design processes support collaboration across business, product, and technical teams
  • Improves cross-functional communication - ADDR is an iterative, team-oriented process that improves quality and speeds delivery by encouraging early alignment on the scope and goals of the API across business-facing and technical roles
  • Incorporates rapid feedback - Good API design relies on both iteration and parallel efforts with frequent feedback
  • Avoids API design anti-patterns - Anti-patterns are usually signs that we learned important details too late. ADDR ensures API design considerations and feedback are factored in early
  • Delivers a repeatable, teachable, and scalable API design process - The ADDR process guides groups through a repeatable, teachable, trackable process

More details about the ADDR process can be found in Chapter 2 of the book.

Back to homepage