Why all API consumer journeys need a map

In the previous blog entry, I described two specific design artifacts (user types and personas) that can be used to inform an intentional API consumer experience. In this entry, we’ll go one step further into the API ecosystem and map out how the consuming developers (i.e., the direct users of the API) work with other user types to achieve their goals. Understanding how all the players come together to support your API consumers is fundamental to developing the right API product as well as the right set of services and support offerings to make your users successful. Journey mapping is a technique used by leading UX and service design organizations to articulate the steps and activities necessary to complete complex, multi-faceted tasks that involve multiple actors across multiple channels. In this article, I’ll explain how journey mapping can be effectively applied to API consumers and give some insight into the various forms and levels of detail that different teams align around when planning different types of experiences.

Personas allow for empathy. Maps provide context.

Journey maps – Journey maps for API consumers are paradoxically less common (compared to user types and personas) in enterprise API programs while also being the most actionable and useful of the three experience design artifacts covered in this blog series. The main difference to pay attention to here is that the user types and personas can be useful as tools, but neither of these artifacts are reflective of the actual experience people will have as they engage your enterprise. Journey map artifacts, on the other hand, are more than representations of people — they are models of the experience that guides a consumer through each step that developers go through as they engage with your product/platform/organization throughout their application creation experience.

Mapping the API consumer journey (in both as-is and to-be forms) provides product owners with a holistic understanding of their target user-base, developer relations, collaborative interactions, marketing strategies, and on-boarding approaches that your enterprise will create and support. This removes friction from the process of taking an application from the drawing board to full scale production. Journey maps can show your API product owners that application creation and API consumption is a team-sport — requiring each of the above user types to achieve the desired end. A pleasant and satisfying experience of leveraging your enterprise’s APIs to make something that is valuable to their stakeholders and customers.

A general framework for the API consumption journey can be mapped via the following phases: Discovery and learning, envisioning and experimenting, developing and troubleshooting, deploy and monitor, and learn and evolve stages.

API consumer journey phases
Figure 1: API Consumer Journey Phases

As consumers move through each of the above phases, each of the other user types interact and collaborate with the consumer and each other to ultimately deploy, scale, and evolve their API-powered applications.

There is no industry-standard template for documenting a journey map, and there are many good examples to choose from. When looking at examples to inspire your enterprise, the key distinction to pay attention to is the level of detail in the diagram to see if it would give your team:

  • An accurate picture that communicates the true level of complexity and duration of the process that people go through.
  • Sufficient insight into the likely mindset of actors inside the journey.
  • Visibility into areas/interactions of pain/delight for the actors inside the journey.
  • An understanding of the moments where value creation is realized for the consumer, your enterprise or all parties involved.

For comparison purposes, I’ve included three examples below that span different levels of complexity in mapping audience journeys. While these examples aren’t API-consumer-specific, they still can be used as both an inspiration of what your API product team can create, and a justification for why your consumer journey map needs to be specific to your industry and context. For example, your authentication and provisioning policies and process are specific to your enterprise, while the goals and emotional states of your personas will be specific to your industry, etc.

Figure 2 – Simple Journey Map template, courtesy of the Nielsen Norman Group
Figure 3 – Experience Map for billing management, courtesy of Harmonic Design
Figure 4 – Complex Journey Map for POS on-boarding, courtesy of Harmonic Design

The map to API consumer heaven is paved with good intentions

Each of the above examples have different strengths and can be used for different purposes. The most simple format (figure 3) is appropriate for a process that has low to medium complexity and doesn’t require interaction by more than a few actors. This format is an intentionally simplified form of a journey map sometimes referred to as an Experience Map (a higher level artifact than a typical journey map). The complex format (figure 4) is more appropriate for mission-critical processes that span over longer periods of time and involve a larger number of actors. Each of these formats are appropriate to help a product team identify what areas of the journey are ripe for improvement or redesign. These maps are the context that allow your API initiative team to articulate, design, and execute a series of efforts that will ultimately culminate in a customer-facing experience that meets the goals of both your enterprise and the API consuming developers.

Whatever format your team picks, the goal you are shooting for is for your API team to have an “as-is” and “to-be” map that articulates how the journey of your API consumers will play out, along with the sense of how the other actors in the ecosystem support that journey. This deliberate approach, detailed with the discrete steps and interactions along the path, is the key to allow your API product owners to create an experience rich in moments of delight as API consumers engage to leverage your platform. Both the MuleSoft and Salesforce teams are well versed in collaborating to create both the underlying artifacts along with the detailed systems to deliver market-leading experiences in the API and integration spaces. 

If this is something your team would like help with please reach out to a member of the MuleSoft account team. Or go to trailhead and learn more about mapping customer journeys.



We'd love to hear your opinion on this post