Delivering high-value APIs using EventStorming

When evaluating the value of an API portfolio, I often encounter APIs set for reuse but ultimately fit-for-purpose. These APIs meet a specific need but will likely have a limited number of consumers due to their particular purpose. 

Some fit-for-purpose APIs include connector APIs that provide wrappers around legacy systems. Others, however, were designed with a single use case in mind, without any additional context to the domain. The result is a portfolio littered with low-value APIs that fail to deliver on the intended ROI established when the API was first conceived. 

EventStorming is a technique that helps with identifying high-value APIs. It looks at the end-to-end process and allows teams to prioritise their roadmap to deliver the highest value possible to all stakeholders. 

Let’s take a look at EventStorming and learn how we can use it to identify high-value APIs as part of your delivery process.

What is EventStorming?

EventStorming is a collaborative process to help surface business processes, workflows, rules, and domain events using a visual model. It is a tool designed by Alberto Brandolini that has been adapted in different ways to fit the needs of organisations worldwide. 

It seeks to create a shared understanding of all or a portion of a domain. You can achieve alignment between stakeholders and development teams through a shared understanding of vocabulary, workflow processes, outcomes, and the resolution of unknowns. A successful EventStorming session helps everyone contribute to these insights and communicate effectively through a fun exercise.

Benefits of using EventStorming during API design

EventStorming can take several shapes and result in a variety of outcomes. For API design, EventStorming offers several benefits:

  1. Surfacing the requirements and scope of the problem being modelled reduces the need to rework or throw away code.
  2. A shared understanding of the workflow processes, business rules, and constraints to ensure that APIs support real-world needs.
  3. Creating a shared domain vocabulary and replacing multiple terms with ubiquitous language ensures everyone has the same understanding.
  4. Identify unknowns that require follow-up and clarification before API delivery when the cost of change is lower.
  5. Identify high-value APIs and corresponding API responsibilities to minimise cross-team dependency coordination.

In short, EventStorming helps to speed the delivery of software, including APIs, while reducing the chance that code will need to be thrown away or changed at the last minute. 

Additionally, it drives an outside-in design approach that ensures APIs focus on delivering high value for the organisation, customers, and partners. This results in a more significant ROI for your API delivery efforts. 

An overview of an EventStorming session

EventStorming sessions are very interactive and are guided by a dedicated facilitator. In-person sessions require an ample wall space called the EventStorming canvas, where colour-coded sticky notes are placed and moved around to construct a narrative of how the solution will work. 

Remote sessions are also possible when teams are distributed or unable to locate a single room of sufficient size or duration. Collaborative tools such as Miro, Mural, and Google Jamboard are just a few ways to support a remote EventStorming session. 

As the EventStorming session evolves, multiple sticky notes denote workflows. Typical workflows use commands (blue stickies) that are sent to aggregates (large yellow stickies) and produce domain events (orange stickies). Hot pink stickies denote uncertainty areas that need further research and refinement. Lilac stickies indicate when specific business logic or rules exist. More colourful sticky notes can further expand your understanding of the domain area. 

Below is an example of an EventStorming session:

The typical approach to EventStorming sessions starts by identifying the domain events, often through a storming session where everyone is composing the domain event sticky notes. Once the storming has been completed, the sticky notes are ordered and missing notes added. 

Commands and aggregates help expand understanding. When there is a question for follow-up, place a hot spot sticky note for follow-up. After everything is complete, review the narrative that has been created. 

The interactive nature of EventStorming ensures everyone is involved. As you may have noticed, this is not a tool for developers. Various roles can participate in the session and are encouraged to contribute their knowledge and expertise. 

Identifying high-value APIs using EventStorming

We can use the details captured on an EventStorming canvas to hint where APIs may exist by examining shifts in the language used throughout the EventStorming canvas. 

As terminology shifts, boundaries start to emerge. Name each boundary and assign a web-based API as a starting point. If you are uncertain, start by looking at the aggregate sticky notes. Use the blue command stickies to offer a starting point for the API’s operations. 

For smaller EventStorming sessions, there may be only a single API, while sessions involving a more extensive scope may result in multiple APIs. Keep in mind that at this stage, we are still learning about the domain and the needs of the solution. 

Boundaries must shift around, consolidate, or split as you learn and explore the domain further. 

Use a sticky note to mark APIs that will deliver high value to your stakeholders. These may be APIs that perform transactional processes that directly generate revenue. Find a way to estimate the value provided for each API call or sequence of API calls. 

In other cases, the value may be indirect and result in deeper integration with your customers, reducing customer churn due to the high cost of change. 

As the list of APIs and their operations take shape, use your API catalogue to discover APIs that may provide the needed behaviour. Use a hotspot (hot pink sticky) to mark areas where existing APIs may be leveraged. 

Then proceed with the rest of the Align-Define-Design-Refine (ADDR) API design process to model your API needs. Once you understand the API you need, you are in an excellent position to identify existing APIs that can speed the delivery process. 

For APIs that do not exist yet, continue through the ADDR process to design your API and gather feedback early and often before the delivery of your APIs. 

Who should be involved in an EventStorming session?

When selecting the participants for an EventStorming session, be sure to consider the following roles in priority order:

  1. Business owners, including those helping to define the requirements, such as product managers and product owners. 
  2. Subject matter experts (SMEs) familiar with the domain space
  3. Technical leads, architects, and senior developers responsible for the software delivery.
  4. Security experts, especially when the problem space requires the involvement of privacy or security concerns.
  5. Individual software developers and contributors that are not involved with decision-making (on a case-by-case basis only).

Keep your sessions to at most 12 participants to ensure that everyone has a chance to contribute. Bigger groups will often prevent everyone from sharing their expertise. 

Consume first, build when necessary

Using the EventStorming process in your API design approach enables your organisation to look at a complete workflow, identify high-value opportunities, and look for existing APIs to reuse with little or no additional effort. This will speed up your solution’s delivery and reduce the cost by encouraging reusability.