Getting Started with ADDR

How to get started with an ADDR design session.

Who Should Be Involved in ADDR?

Most software development involves several people across a variety of roles. Business leaders and product owners analyze market needs. Software architects and technical leads map out the important design decisions for the solution. Developers design and write the code that makes it all work. Designers and user experience (UX) experts pull everything together into a user interface, with an eye toward usability.

The following roles should be involved through the ADDR process:

  • API Designers and Architects - Facilitate the design process and provide expertise
  • Domain Experts/SMEs - Clarify requirements and share the vocabulary of the design
  • Product Owners - Guide API design to match customer needs and market opportunities
  • Technical Leads - Guide implementation efforts and help clarify ongoing questions
  • Technical Writers - Ask clarifying questions, shape design and properly document its use
  • QA Teams - Provide expertise on how and when to test (from the very start)
  • Infrastructure/Ops - Ensure network, platforms, servers, and the API management platform (AMP) are properly configured and available
  • Security Teams - Review initial designs, identify risks, review potential attack vectors, help manage data (PII, NPI)

Typically, domain experts and product owners are needed most during the Align and Define phases, while the API designers and architects, technical leads, and technical writers increase their involvement as the process transitions from the Define Phase to Design and Refine.

Where should I start in the ADDR process?

You may be uncertain where to get started, based on how their current stage of API design. The following guidelines can help teams jump into the right step, avoiding unnecessary rework:

  • If you are designing a new API or enhancing an existing API: Begin with the Align Phase by creating job stories. If you have already performed some scoping and requirements gathering as part of your solutioning, this should go quick. For teams starting out with a new solution, the Align Phase is an important step to understand and empathize with the needs of your end users and developers.

  • If you are further along in your API design but need some additional clarity: Start with the Define Phase by modeling your API resources and operations (step 4) using whatever assets you have already. If your API design is less than optimal and needs a fresh start, start from the Align Phase to gain a better understanding of the desired outcomes of your end users.

  • If you are preparing for an API design review for an existing API: Jump to the Refine Phase to capture design artifacts that communicate your API design intent and how it will satisfy the jobs-to-be-done. Based upon your feedback, you may need to revisit some of the previous phases of ADDR to gain a better perspective on the needs of your end-users that will deliver an improved API design.

Back to homepage