Build a successful API by understanding user personas

Bruno Pedro

May 16, 2023

Postman Open Technologies Knowledge Base is a new project with the goal of providing insights from a vast amount of information about APIs available on the internet. One of the project’s objectives is to provide an API that consumers can use to retrieve information from the Knowledge Base. The result? As part of my work on the Postman Open Technologies team, I have been building the Knowledge Base API.

I’ve naturally started by following our Postman team’s internal API Design Playbook. The playbook is a series of steps that help anyone building an API come up with a solution that meets the needs of consumers. (Stay tuned for when I make this publicly available!) The API design steps covered by the playbook are strategy, definition, validation, and finally, specification. I started the design of the Knowledge Base API with the strategy step, where the goal is to document why the API should be built. The output of the strategy step consists of findings and evidence that back the importance of building the API.

Finding evidence that the API should be built can be done by understanding and analyzing potential consumers. And that’s precisely what I have done: I have identified the user personas that can benefit from using the Knowledge Base API:

1. Technical researchers

2. API designers

3. Product managers

4. Technical architects

How do you identify user personas for an API?

To identify the four user personas, I engaged with people from each of the categories in a series of interviews. I wanted to understand what their work was like and what challenges they were facing. I also wanted to validate my initial hypothesis that they would be interested in the Knowledge Base API I was designing. Not only was I able to confirm most of my assumptions, but I also enriched the information I had with feature requests. So, for example, a product manager revealed that it would be interesting to get information about API design trends. A researcher gave importance to knowing the provenance of the data used in the Knowledge Base.

I then used the information from the interviews to create my catalog of user personas. For each user persona, I have identified their jobs-to-be-done (JTBD), the tools and services they use, their work-related challenges, the benefits they would get from using the Knowledge Base, and their potential behaviors when using the API. These attributes helped refine the user personas and will help me design the different elements of the API once I get to that stage.

At this point, it’s worth remembering that user personas are fictional characters representing a specific type of person who will be using the API. Each persona has unique characteristics, such as JTBD, benefits, behaviors, and challenges. For example, a technical researcher may be interested in using an API to gather data for academic research. In contrast, product managers may be looking for an API that helps them analyze customer behavior and preferences. The important thing is that you’re able to identify a cohort of users with each of the personas.

Benefits of knowing your audience from the start

Let’s get back to my journey designing the Knowledge Base API. With all the user personas identified and documented, I could then start focusing on defining other attributes of the API. By knowing the tools each persona uses, I was able to identify the best architectural style for the API. With the benefits documented for each persona, I could define the API capabilities. JTBDs and behaviors helped me identify the API resources and operations. Altogether, the different attributes of user personas can continuously inform how I design an API that reflects what potential consumers need. And that is critical to making an API successful.

In summary, APIs explicitly designed for targeted users are more likely to be adopted. Those APIs directly address the real-world problems or goals of users. Aligning APIs with user personas’ needs and behaviors from the start will yield better outcomes than assuming what is best and hoping that users will engage.