Introducing the ADDR API First Design Process

I am pleased to announce the release of my latest book, “Principles of Web API Design: Delivering Value with APIs and Microservices”. This book helps teams and individuals transform their product and business requirements into one or more APIs. The book introduces a repeatable, scalable process for API design called Align-Define-Design-Refine, or ADDR.

Let’s explore the book by looking at the ADDR process and why I think it is an effective way to take an outside-in approach to API design by focusing on outcomes, activity steps, and then designing APIs to satisfy those outcomes.

What is API design first?

API design first shifts the focus from code to designing an API with a focus on delivering a great developer experience for your API consumers. It recognizes that both developers and end-users benefit from a thoughtful API design approach.

An API design that looks good to the designer may not solve the problems at hand. If an API is designed by taking a code-first approach, the focus of the design will be on the internal implementation details. Optimizations are made for the delivery team rather than the API consumer. This results in a poor developer experience for your API consumers that wish to integrate your API into their solutions.

For organizations to undergo digital transformation, the first step is shifting the culture to an API design first approach. This requires a fundamental change in the way that enterprise IT and engineering teams approach their API efforts. With an API design first approach, teams take an outside-in approach to API design. They recognize that coding is important but an API design is more important to guide the development process. Otherwise, the API design is emergent, focusing on coding details rather than delivering on the desired outcomes of the end-user.

The need for an API design process

One challenge with API design first is that there hasn’t been a prescribed way to go from business and product requirements to an API design that delivers on the desired outcomes of your developers and end-users. I witnessed teams struggle with how to organize and align their understanding of the requirements into an effective API design. Time was wasted arguing about design elements and processes.

Without a structured approach to your API design process, teams end up in “analysis paralysis” as they try to design their API. They spend more time trying to design and re-design their API, without any clear understanding of what the end user wants to do. The result is design thrash and front-end rework as the API design changes over-and-over again.

That is why I created the ADDR process. It offers a framework for gathering requirements into a simple series of artifacts that guide you through the API design process. It encourages alignment with business and product teams, along with fast feedback that ensures you remain agile as you gain insights into the needs of the developers and end users.

As your organization scales beyond a small number of APIs, it is important to equip teams with a repeatable, scalable API design process. The process must also ensure alignment and cross-functional communication between business, product, and software engineering.

Let’s look briefly at the ADDR design process that is detailed in the book.

The ADDR Scalable API 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.

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

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

There are several benefits to adopting the ADDR process:

• Aligns Business and Technology with 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 Stakeholder 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 Scalable Process - The ADDR process guides groups through a repeatable, teachable, trackable process

Let’s look at each phase in more detail to better understand how the ADDR process works.

The Align Phase

Goal: 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.

The Align Phase is the most critical phase and often the most overlooked. Rather than immediately starting to write code, this phase focuses on ensuring that the team response for API design have sufficient understanding of the responsibilities of the API. This prevents building an API that delivers raw data but fails to deliver outcomes desired by the end user or developer.

The Align Phase consists of two activities:

1. Identify digital capabilities: Identifies the customer needs and desired outcomes to address the jobs to be done (JTBD), written as job stories
2. Capture activity steps: Expands the digital capabilities to include the list of activity steps required to go from a problem or situation to the desired outcomes identified by the job stories. For complex or unknown problem domains, this may include using collaborative techniques such as EventStorming to explore and understand it prior to identifying the activity steps

The Define Phase

Goal: Map the activity steps into one or more API profiles that describe the APIs and how they will deliver on the desired outcomes.

The Define Phase acts as a bridge between requirements, identified in the Align Phase, and the API design that will be created. During the define phase, teams will focus on mapping the activity steps into one or more API profiles. An API profile defines the scope of responsibility of the API, the API operations that will be needed, the API resources that are required, API security concerns, and opportunities for business events that will be emitted. The Define Phase is also used to identify existing APIs that can be leveraged, encouraging reuse of APIs in your catalog.

There are two activities that are used in the Define Phase:

1. Identify API boundaries: Groups the digital capabilities into API boundaries and determine if existing APIs may be leveraged or if new APIs are required
2. Model each API: Define the high-level API profile, including resources and operations needed, and the events it will event. The API profile also identifies authorization scopes that may be required based on who is (and is not) allowed to perform the operation.

The Design Phase

Goal: Transform the API profiles into using one or more API styles including REST, GraphQL, and gRPC.

The Design Phase is where the technical details are applied. First, select the API style or protocol that best fits the needs of the API consumers: REST, GraphQL, gRPC, or something else. Then, map each API profile into the selected API style. It is encouraged to use a tabular format for this step, prior to documenting your API using the OpenAPI Specification or other documentation format, as this makes it easier to make quick changes based upon feedback in the Refine PHase.

In some cases, you may need to use the API profile to design more than one API style or protocol. For example, you may choose to design all of your APIs using a REST-based approach, but also offer a GraphQL-based API for more advanced query support and response shaping.

There is only one activity for the API design phase, but it will be repeated for each API profile you are ready to design and deliver:

1. High-Level API designs: Selects one or more API styles that each API profile will offer and document the high-level design elements

The Refine Phase

Goal: Incorporate fast feedback to improve the API design through the use of documentation, prototyping, and testing efforts.

Before embarking on the full code delivery process, it is a good idea to refine your design through fast feedback from your API consumers. Create diagrams, README documentation, or other assets before committing to your API design. API mocking tools are always a great way to help people experience your API before you code it up. Make any design adjustments based upon feedback, then finalize the first version of your API reference documentation and getting started guides.

There are two primary activities in the Refine Phase, although you may need to create a variety of artifacts to help communicate your API design and intended usage to your consumers for feedback:

1. Refine the design: Incorporates design feedback from API consumers using techniques that encourage improvement in the developer experience
2. Document the API: Completes the API documentation, including reference documentation and getting started guides, to accelerate integration

A look inside the book

The book is divided into give parts, starting with the principles of web API design, then a step-by-step review of each recommended activity across the four phases, and finally an HTTP primer for those that need a quick review.

As you read the book, you are guided by the ADDR process through a real-world example with sample artifacts produced along the way. Using this example, you will be able to quickly apply the ADDR process for your own API design efforts.

Below is the table of contents:

• Part I: Introduction to Web API Design
  • Chapter 1: The Principles of API Design
  • Chapter 2: Collaborative API Design
• Part II: Aligning on API Outcomes
  • Chapter 3: Identify Digital Capabilities
  • Chapter 4: Capture Activities and Steps
  • Chapter 5: Identifying API Boundaries
  • Chapter 6: API Modeling
• Part IV: Designing APIs
  • Chapter 7: REST-Based API Design
  • Chapter 8: RPC and Query-Based API Design
  • Chapter 9: Async APIs for Eventing and Streaming
• Part V: Refining the API Design
  • Chapter 10: From APIs to Microservices
  • Chapter 11: Improving the Developer Experience
  • Chapter 12: API Testing Strategies
  • Chapter 13: Document the API Design
  • Chapter 14: Designing for Change
  • Chapter 15: Protecting APIs
  • Chapter 16: Continuing the API Design Journey
• Appendix: HTTP Primer

Check out the publisher’s website to preview the book and learn more.