The ADDR API Design Process
Aligning on the digital capabilities of your API
Digital capabilities are assets that turn desired outcomes into reality through automation. They offer the workforce, partners, and customers the ability to interact with the organization digitally. APIs design is outcome-based and should not be designed in isolation.
Step 1: Compose job stories with desired outcomes
The ADDR process uses job stories to capture the outcomes that APIs will produce. Job stories resemble user stories but focus on three elements:
- WHEN (the trigger event) – the reason the customer desires an outcome
- I WANT TO (the capability) – the action the customer needs to be taken
- SO I CAN (the outcome) – the result of applying the capability at the trigger event
Example job story:
When starting with job stories, teams are able to focus on the minimum API design required to deliver upon the desired outcomes of developers and end users.
What about user stories?Teams are not required to create job stories if their user stories or use cases satisfy the same elements. However, the shift to job stories helps some teams to apply a product mindset, rather than focusing on features, during API design.
No matter the format used, the result should be a focus on capturing the problem (i.e., the trigger event) and desired outcome.
Tips for composing job stories can be found in Chapter 3 of the book.
Step 2: Expand job stories into activity steps
Once an initial set of job stories have been captured, the next step is to decompose the outcomes into the activity steps required.
Starting with one or a few related job stories, work through the steps required to achieve the outcome. For ordered workflows, these will be the steps required along the way. For more open-ended flows, captures all of the steps by exploring the common paths that may be taken to achieve the outcome for each job story.
Capture the details into a activity steps worksheet:
Example activity steps:
Tips for decomposing job stories into activity steps can be found in Chapter 3 of the book.
Optional: Use EventStorming for collaborative exploration
Converting job stories into activities and steps works well when the requirements are clear, and the domain is well known. When this isn’t possible, use a collaborative technique called EventStorming to explore the group of job stories prior to capturing the activities and steps.
EventStorming is a collaborative activity to surface business processes, requirements, and domain events. It produces a visual model that is based on the input of subject matter experts (SMEs). EventStorming is most effective when conducted in-person and with the help of a facilitator.
Example of a completed EventStorming canvas:
Once an EventStorming session is complete, use the canvas to identify activity steps (see step 2, above). It will also help you with identifying boundaries during the Define phase.
Unify your vocabulary!It is at this point that vocabulary should be unified. If activity steps or EventStorming sticky notes use different words to mean the same thing, unify and clearly define the terminology.
Your vocabulary will be important during the API define and design phases, as the terms are often reflected in resource and operation names. Inconsistent vocabulary early in the process will only serve to create an inconsistent and hard-to-understand API design.
More details on capturing activity steps and conducting EventStorming sessions are found in Chapter 4 of the book.