The design of a web API is a separate and critical step of software delivery. The process of API design requires communication that extends beyond the developers that will deliver the API. When executed properly, an API design process helps to course-correct wrong assumptions while aligning business, product, and technology teams on the essential elements of the web API. Let’s dig into the details of establishing an effective web API design process that seeks to align all stakeholders, resulting in a great API design that considers both business and developer needs.
Why an API Design Process?
It is important to recognize that teams can design and deliver an API successfully without the need for a formal API design process. I have worked with many companies across the world that have managed to deliver an API into production without any kind of consistent approach to API design. However, the APIs they produced took longer to deliver as they required multiple iterations of redesign followed by significant code changes. While I acknowledge that when code meets reality, change will always be required. But there is a difference between making a minor change to accommodate a newly-discovered insight and performing significant code modification that results in a backlog of technical debt.
An API design process encourages efficiency throughout the delivery process. By focusing on the API contract from an outside-in perspective, the design represents the needs of users and developers as a primary concern. Implementation details are less likely to leak into the API design, making the API more resilient to internal implementation changes over time.
It also prevents the backend API from becoming the primary blocker for any front-end delivery schedule. Without an effective API design process, front-end developers are forced to wait until the backend developers have completed the API implementation before they can integrate it. Only then will the front-end developer realize the API design doesn’t match their needs, forcing more rework by the API team and a longer delivery schedule.
An API design process is a predictable method of moving from business requirements to an API design. The goal of API design is to make it easier to discover, integrate, and deploy solutions in a way that is scalable for the organization while delighting the developers that will integrate them into their solutions.
What is API Design First?
APIs are forever. Teams can always add to an API design, but it is impossible to take things away without breaking integrations that depend upon them. 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 to 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 it doesn’t always happen in a linear process. Code and data may already exist and must be leveraged from an existing system. API design-first doesn’t require strict adherence to a greenfield process, but it does seek to incorporate 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 APIs design exist before development begins. It does require cross-functional teams that are able to contribute their subject matter expertise alongside existing code and data.
The Align-Define-Design-Refine Process
The Align-Define-Design-Refine (ADDR) Process is a lightweight approach that guides organization through an API design-first approach. The process groups the step-by-step process 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: Identifies the customer needs and desired outcomes, including the corresponding digital capabilities that are required.
- Capture activity steps: Expands the digital capabilities to include a unified understanding and clarity through collaborative API design sessions.
- Identify API boundaries: Groups the digital capabilities into API boundaries and determine if the APIs already exist or if new APIs are required.
- Model API profiles: Uses a collaborative API modeling session to define the high-level API design including resources and operations into an API profile.
- High-Level API designs: Selects one or more API styles that each API profile will offer and document the high-level design elements.
- Refine the design: Incorporates design feedback from API consumers using techniques that encourage improvement in the developer experience
- Document the API: Completes 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:
Getting Started with the ADDR Process
Want to get started applying the ADDR process? Attend the Collaborative Web API Design, a 3-day workshop that helps product managers, architects, and developers to learn and apply the ADDR process.
The workshop will help you:
- 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, for API design and delivery
- Create a repeatable process that delivers an API design with a group composed of technical and non-technical roles
- Communicate more effectively through collaborative design sessions and artifacts
- Transform the organization with a healthy, sustainable, and successful API program
The content in this workshop has been delivered to thousands all around the world to help organizations in a variety of industries including: banking, commercial insurance, hospitality, airline, and travel.
Can’t make the workshop? Then purchase Principles of Web API Design: Delivering Value with APIs and Microservices, my latest book that discusses the process in-depth. When you are ready, join us in the workshop to gain some hands-on experience applying the process in real world scenarios.
