Reading Time: 14 minutes

A close friend and mentor of mine (Patrick Quattlebaum of Harmonic Design) once said “All systems have a design. The question is ‘is the design intentional or random?’” What he meant is that the design of interfaces created inside an enterprise (graphical or not) communicate how much that organization values the time and effort of their users. In addition to functional communication, these interfaces also communicate your enterprise’s commitment to low-friction experiences. In the world of APIs, this commitment can be seen in terms of taxonomies and signatures that are consistent, intuitive, and coherent. Additionally, the ways APIs work together cohesively to allow for streamlined completion of core use cases communicate that an enterprise values the API consumer’s time and effort.

The list of human factors to consider in your design process can quickly become overwhelming without a framework to understand, contextualize, and prioritize them. Luckily for the API community, the UX and service design disciplines have been around long enough to provide a set of approaches and tools for leveraging in our API transformation initiatives.

Artifacts and archetypes

latest report
Learn why we are the Leaders in API management and iPaaS

If you’re working in an API context and have never encountered user types, personas, or journey maps, you’re not alone. Even if you have seen these types of artifacts, it’s uncommon for them to be used within an API context given that many people think UX is a discipline that is about “pretty pictures and wireframes.” In recent years, as developer relations and API ecosystems have gained traction in the enterprise, many longtime advocates of the developer experience have created different approaches and tools to formalize a path for making an intentional and optimized experience for API consumers. Within this blog series, I’ll speak to three key artifacts that allow an organization to plan and design experiences that are compelling to their core audiences: user types, personas, and journey maps.

User types 

While personas are high-fidelity artifacts that provide insights on the attitudes and emotions of users, user types are less concerned with demographics and backstories. User types are lean artifacts used in product strategy contexts to support decision making from a behavioral perspective with high-level factors like observed behaviors, opportunities, pain-points, and frequent scenarios in which users find themselves.

A typical model for user types is to compare two aspects that allow for conversations and decision making to happen with a common frame of reference about what’s important to different ecosystem players. For example, consider the different types of shoppers a large retailer might service. How would they compare on a two-dimensional diagram with an expected level of customer service on one axis and purchase likelihood on the other? You might end up with user types like these:

This same approach can be applied in an API consumer context, where a user-type map might look like this:

Figure 1: Simple user type/segment map

In the diagram above, the vertical axis represents the amount of influence a user type has over the decision to use a particular provider of APIs. While the horizontal axis represents the direct interaction that exists between the user type and the actual API products.

The hypothetical user types above can be annotated with details (as shown in the generic example below) to help understand the goals a prospective user might have in a particular interaction. The user types in the below example are fairly generic and need some form of grounding to be effective as planning tools in an API consumer experience initiative. Practically, this means having a level of commitment to perform user/market research to inform and validate the hypothesis which is too flat and speculative for a business-critical initiative. Depending on the scale and goals of your effort, this research can be a series of interviews, surveys, or a mix of qualitative and quantitative activities designed to surface unique insights and unmet needs.

Figure 2: Low-fidelity API consumer user types.

In both of the diagrams above, it is important to take note of the non-API consumer types because these user types are often deeply embedded in the activities of co-creation. For example, the “enabler” user type which represents the set of actors who live in between API creators and API consumers has the potential to make or break your API consumer experience in the eyes of the API consumer (who is often your most important user type). In your organization, this might be a developer relations team member who focuses on public events or a support team member who helps customers get credentials for sandbox experiments.

It might be tempting to ask “why do we need to understand the enablers when they aren’t the direct users of my consumer experience?” This perspective has a couple of gaps within it:

  1. Consuming users don’t engage in a vacuum: Consuming users will need support whether you have dedicated staff or not. The question here is “how will the needs be surfaced and met?” Ask your product leadership whether they want to trust random/ad-hoc channels outside of their influence to help their customers or if they’d prefer to have a fully functional channel that can support API consumers just like they would get help with any other type of scaled product or service.
  2. User types and personas aren’t an experience/service design: Noting that modern online experiences (inclusive of API engagement) across multiple channels, journey maps (detailed in the follow-up article) become a critical part of planning a curated and low-friction path for an API consumer to move through a funnel process to an ultimate conclusion of production API usage.


Personas are fairly commonplace artifacts for planning offerings and experiences targeted to specific audiences. UX and other design disciplines have refined the persona generation and validation process for more than two decades and many technology professionals use them to empathize with user concerns. It’s important to understand that personas are not sufficient to craft a holistic experience design that crosses channel boundaries (both online and physical in many cases).

Personas have more detail in high-fidelity artifacts that give insight into the attitudes and emotions of users as they approach and execute a task, user types are less concerned with demographics and backstories. Personas are used in detailed design contexts to support decision making from demographic and emotional perspectives with factors like age, cultural concerns, or technical ability. For example, the “maker” user type in Figure 2 may relate to two or more personas that represent the breadth of expertise that is represented in your developer community (e.g., hobbyist developers vs. enterprise full stack experts).

Personas are more context-specific than user types as well. For example, if you’re in the financial services sector, the user types might apply to your scenarios, but personas would require specifics connected to financial services contexts (where the specifics would typically come from qualitative user research in the form of interviews, shadowing or focus groups). It is possible to make detailed personas based on hypotheses in the form of “educated guesses,” but it injects the risk of insular thinking which has to be weighed against the criticality of your API initiative.

Seek first to understand, then to be understood

Personas and user type artifacts are great tools to get started in envisioning an API consumer experience that is grounded in empathy with your target audiences. The next step is to make a practical and actionable plan around how these audiences will interact to turn inspiration into business advantage. My next article will discuss API consumer journey maps and how these artifacts can be used as the pivot point between empathy for users (understand your users) and a plan to service them (help them understand and engage with you).

Whether you’d like to learn more about persona development or about advanced journey mapping techniques within API and integration contexts, the MuleSoft team is here to help you. Please reach out to your Muley friends via LinkedIn.

Series NavigationWhy all API consumer journeys need a map >>