APIs are no longer solely the territory of programmers and computer science majors. APIs are big business. They also drive big business. This new reality means the C-Suite is far more involved in the API design process than they were in the early days, requiring enhanced communication between the business and technical sectors of an organization.

The Align-Define-Design-Refine (ADDR) Process is the result of these shifting needs. It’s designed to get everyone on the same page to design and create scalable APIs.

To help you learn how to integrate ADDR into your API design, we’ve talked to the creator of the process, author, and API consultant, James Higginbotham. We’ll start by digging into ADDR and then finish with a short interview where he clarifies some of the concepts.

How Align-Define-Design-Refine Improves API Design

Creating APIs as you go can create all manner of problems down the line. It’s in everyone’s best interest to adopt a design-first approach to designing, developing, and implementing an API. In basic terms, design-first means taking a moment to think through some details before writing code. Taking the time to put a structure in place will make future revisions infinitely easier.

A design-first approach starts by identifying your API’s intended capabilities. From there, you’re better able to make them happen. Each of these stages doesn’t necessarily happen in a straightforward fashion. There may be multiple teams working on the same project, for example. The ADDR Process helps ensure everyone is on the same page and the API design process is as efficient as possible.

Introducing the ADDR Process

Let’s start with an overview of the ADDR process.

• Align: This step is where you make sure that every team understands one another and is working towards the same goal. The business and technical sides come together during the Align phase, agreeing on goals and intended outcomes. Once you know what you’re trying to do, it’s much easier to do it.
• Define: The next step is where you take all the different goals and begin to translate them into technical language.
• Design: Now you’re ready to begin creating your API. During the Design stage, you’ll take the goals you identified during the Define stage and start to decide on intended solutions. You’ll determine what architecture style will best serve different applications, like using REST or GraphQL for various components, for example.
• Refine: The final stage of ADDR allows for testing, taking in user feedback, and integrating it back into the design process.

Higginbotham goes on to identify seven additional stages that occur throughout the ADDR process.

1. Identify digital capabilities.
2. Capture activity steps.
3. Identify API boundaries.
4. Model API profiles.
5. Perform high-level API design.
6. Refine the Design.
7. Document the API.

In his book, Principles Of Web API Design, Higginbotham identifies the intended goals of adopting ADDR for API design:

• Deliver an API design that emphasizes and solves the customer problems using a vocabulary they understand.
• Reduce the constant design churn common with informal design processes.
• Optimize the entire organization, not just developers, but for API design and delivery.
• Avoid unnecessary steps whenever possible to expedite delivery.
• Create a repeatable process that delivers an API design with a mixture of technical and non-technical roles, some of whom don’t fully understand the nuances of API design but can contribute their insights.
• Produce artifacts that may be referenced within the team and shared across the organization, rather than some scribbles on a whiteboard that fail to communicate reason and intent about the resulting API design.

How ADDR Improves API Design

The ADDR Process is like a microcosm of your API’s whole lifecycle. It’s ideal for prototyping, collecting actionable feedback, and then working that feedback into the development process. ADDR also lets you translate plain language into code. Higginbotham uses the example of a Job Story to illustrate what this might look like.

In this scenario, he uses a situation where someone’s forgotten their password and wants to reset it so they can log back in. In this example, forgetting the password is the Trigger Event. Resetting the password is the Capability and logging back in is the intended outcome.

ADDR ensures that every component of your organization is on the same page. It lets shareholders, end users, and developers speak the same language so you can work together towards realizing your goals.

Interview With James Higginbotham on ADDR

Now let’s finish with our interview with James Higginbotham, where he goes into even greater detail about the ADDR process, how to implement it, and some of its intended uses.

Why did you create the ADDR process? What inspired it?

The ADDR process is an API design first process that helps teams and entire organizations transform the way they approach API design. I created it as a result of coaching global organizations on a repeatable, approachable process that encourages collaboration across IT, business, and product teams. Too often, teams were starting to code their APIs before they really understood what they were meant to do. The ADDR process is the answer to that.

ADDR started as a technique simply termed “API modeling” and was captured in the book written by myself and Keith Casey. Over time, I realized that teams needed a bit more structure before and after API modeling. ADDR guides teams from requirements to an API design in a repeatable fashion. It builds upon the work of so many, from those in business process engineering to those in product design and iterative software design and development.

Who has used this approach successfully?

I’ve seen ADDR applied to a very large North American bank, a worldwide hotel chain, private banking and investment institutions, a fast food sandwich chain, and commercial insurance. In each of these instances, ADDR was used to equip teams around the world to approach their API designs first from a human perspective. It answers questions such as:

• Who will be using this API directly or indirectly?
• What problem has led them to need the capabilities that the API will provide?
• What is the workflow associated with solving the problem?
• What API operations will I need to support solving this problem?
• How will the choice of API style impact my API design?

What are the net outcomes?

A fundamental tenet of the ADDR process is that API design is collaborative. This means including key stakeholders early and often, rather than thinking of the API purely as a technical concern left to developers. I have seen teams assuming they know the API design necessary to address the problem at hand, to reaching that moment when they realize that the design would have been wrong and they would have wasted hundreds of developer hours throwing away code that they were about to write. I’ve seen product owners realize that APIs are products that must be managed just like any other digital product. Finally, I’ve witnessed executives that realize the value of investing in APIs to create a portfolio of digital capabilities simply by getting hands-on during an ADDR session.

You outline ADDR well in this post on the Stoplight blog, but is there anywhere else readers can learn more about this process?

ADDR is featured in my recent book, Principles of Web API Design: Delivering Value with APIs and Microservices. In the book, I walk you through each step of the ADDR process. It takes you from an idea to an API that is designed using multiple API styles, including REST, GraphQL, and gRPC. I also address the growing need for asynchronous APIs, or Async APIs for short, that enable bidirectional communication between products and organizations.