One of the challenges teams face when designing an API is determining how to move from business requirements into an API design. Teams want to have the confidence that the API they plan to deliver meets stakeholder needs. In addition, they want to know that business and tech teams are aligned throughout development to prevent last-minute overhauls of the API design and underlying implementation.
The Align–Define–Design–Refine process, known as ADDR, is a process framework that guides teams through a repeatable, scalable API design process. This process has been taught globally to product owners, software architects, and developers as a method of taking an outside-in approach to API design. Let’s look at why we need the ADDR process, how it works, and how the Align Phase is used to guide teams toward an effective API design.
API Design is Forever
API design is a communication process. It communicates the digital capabilities offered by an API to external and internal developers across the team and organizational boundaries. Those outside of the API-producing team that will consume the API cannot, and should not, be required to read the actual code of the API to fully understand how it works. In fact, external developers may not have access to the source code at all. Therefore, the API design and any subsequent documentation should strive to communicate with developers in the simplest way.
Teams can always add to an API design, but it is impossible to take things away without breaking integrations that depend upon them. This is why Werner Vogels says, “APIs are forever.” An API design-first process enables teams to move quickly, thoughtfully, and with the agility to make changes early in the process. It is the complete opposite of a waterfall-based approach to API design.
Taking an API design-first approach starts by identifying the capabilities to deliver, then moves toward an API design to meet the desired outcomes – all before writing a line of production code. Of course, reality dictates that these steps don’t always happen in a linear process. Code and data that already exist must be leveraged from an existing system. API design-first doesn’t require an unconstrained greenfield process, but it does require incorporating learning throughout.
The goal of API design-first should be to gather sufficient details to limit the risk of a breaking change in the future. It doesn’t mandate that an entire API or a series of API designs exist before development begins. However, it does require cross-functional teams that are able to incorporate their subject matter expertise alongside existing code and data.
Introducing the Align-Define-Design-Refine (ADDR) Process
The Align–Define–Design–Refine (ADDR) Process is a lightweight approach that guides organizations through an API design-first approach. The process groups the steps into four distinct phases:
- Align: Ensures alignment of understanding and scope across business, product, and technology around a set of desired outcomes.
- Define: Maps business and customer requirements into digital capabilities that will form the basis of one or more APIs to deliver the desired outcomes.
- Design: Applies specific design steps for each API to meet the desired outcomes using one or more API styles including REST, GraphQL, and gRPC.
- Refine: Refines the API design through feedback, documentation, prototyping, and testing efforts.
Across these phases are seven steps:
- Identify digital capabilities: Identify the customer needs and desired outcomes, including the corresponding digital capabilities that are required.
- Capture activity steps: Expand digital capabilities to include a unified understanding of the activity required and improves clarity through collaborative API design sessions.
- Identify API boundaries: Group the digital capabilities into API boundaries and determine if the APIs already exist or if new APIs are required.
- Model API profiles: Use a collaborative API modeling session to further define the API design into an API profile including specific resources and operations.
- High-Level API designs: Select one or more API styles that each API profile will offer and document the high-level design elements.
- Refine the design: Incorporate design feedback from API consumers using techniques that encourage improvement in the developer experience.
- Document the API: Complete the API documentation, including reference documentation and getting started guides, to accelerate integration.
The diagram below illustrates the steps that make up the ADDR process:
Aligning on API Design
Effective API design incorporates the needs of customers. In this context, customers are defined as a segmented group of developers and end users whose experience will be shaped, for better or worse, by the API design. Keeping an API design in alignment with customer needs helps to deliver a great user and developer experience.
The ADDR process establishes this alignment with the Align phase, which helps define the digital capabilities necessary to deliver desired outcomes. It builds upon the Jobs to be Done, captured as job stories, that define those outcomes. It then expands into the activities and steps that make up the job.
Jobs to be Done (JTBD) are identified needs that can be fulfilled by a product or service offering. JTBD captures a customer problem, the task to be performed, and the desired outcome that should result.
Job stories capture the Jobs to be Done for any product, including the customer motivations, events, and expectations for a new product, service, or API. They seek to identify the problems that customers have and the eventual outcome they wish to achieve. They are composed of three components: the triggering event, the job or capability required, and the desired outcome.
By using this format, a product owner or developer can capture the important elements that the API is designed to solve. Typically, job stories precede user story creation in an agile software development process. Job stories may then be decomposed into related activities and steps. This helps to identify the various API operations that will need to be designed.
During this effort, communication between stakeholders helps to ensure that the API design will properly align with the needs of the customers, partners, and developers that will interact with the API. Assumptions are clarified and a more concrete set of needs emerge that the API design will be required to fulfill. The ADDR process uses this initial set of artifacts to drive toward a more effective API design that is aligned with all parties.
The Bottom Line
No matter what API design-first process you implement, be sure it takes an outside-in approach that focuses first on the outcomes to be delivered. This Jobs to be Done approach shifts the conversation of the API design from a technical discussion to one that adds value to your customers, partners, and workforce. ADDR incorporates this approach into a step-by-step framework for an effective API design-first methodology.
If you wish to learn more about the ADDR process, pick up a copy of my latest book, “Principles of Web API Design: Delivering Value with APIs and Microservices”.
This is an excerpt from James Higginbotham, author of Principles of Web API Design: Delivering Value with APIs and Microservices. Follow James on LinkedIn for more.
