What I learned from interviewing potential users before designing an API

This post was originally published on the Postman blog as “What I learned from interviewing potential users before designing an API”. The original content was professionally edited.

I’ve been working on the Postman Open Technologies Knowledge Base project with the goal of implementing the Knowledge Base API. I’ve followed the API design steps we use internally: strategy, definition, validation, and specification. This blog post explores my journey through the strategy step, particularly the part where I interview API stakeholders. The output of the strategy step consists of findings and evidence that back the importance of building the API, and interviewing stakeholders provides key information that I use to reinforce the value of the API. Keep reading to learn more—and stay tuned for a follow-up post that goes into greater detail about how I identified the architectural style of the API by learning from users what tools they use.

After identifying the user personas for the Knowledge Base API, I contacted people representing each cohort to understand their needs and challenges better. This process involved conducting interviews to obtain information that would inform me about what these people do daily, the challenges they face in their jobs, the tools and services they use regularly, what they would gain by using the Knowledge Base API, and what their behavior would be while interacting with it.

As I began conducting the interviews, the feedback I obtained from real people representing each user persona was essential. These interviews allowed me to better understand the needs and pain points of the various users, which helped validate some of my initial assumptions and provided me with new insights.

Learn users’ jobs-to-be-done #

One of the main areas of focus during the interviews was identifying the jobs-to-be-done (JTB) for each user persona. Understanding each persona’s daily tasks and responsibilities helped me identify their specific needs and how the Knowledge Base API could help them achieve their goals. For example:

An API designer: One user persona was an API designer who frequently needs to identify if an API follows a generic REST style. The Knowledge Base API could help this user quickly analyze the API being reviewed and compare it to the REST architectural style.

Additionally, identifying the challenges users face in their jobs was another critical area of focus during my interviews. By understanding the specific pain points of each user persona, I was able to determine how the Knowledge Base API could address their needs and make their jobs easier. For example:

A researcher: One user persona was a researcher who needs to make data-driven decisions regularly. The Knowledge Base API could help this user quickly access the information to support the decision-making process, saving them time and improving their efficiency.

Learn users’ tools and services #

I also asked about the tools and services they use regularly. This information helped me to identify potential integration opportunities with the Knowledge Base API and understand how it could fit into their existing workflows. For example:

A product manager: One user persona was a product manager who frequently uses spreadsheets and other data manipulation tools. The Knowledge Base API could be integrated with these tools to make it easier for the user to access relevant information while working on a project.

Learn how users can benefit from an API #

Another crucial area of focus during the interviews was identifying what users would gain using the Knowledge Base API. Understanding the benefits of the API from the perspective of each user persona was essential to ensure that the API could meet their specific needs and solve their pain points. For example:

A technical architect: One user persona was a technical architect who would benefit from the Knowledge Base API’s ability to find and organize content to produce learning material easily.

Listening goes a long way #

By conducting these interviews, I was able to enrich all the user personas with factual information coming from interviewing real people. This process helped me to validate some of my initial assumptions and identify new insights about the needs and pain points of the various user personas. Additionally, it helped me to design an API that was better suited to meet the specific needs of each user persona.

Gathering feedback directly from potential users is a critical component of developing an API that meets the needs of its audience. By identifying the jobs-to-be-done, challenges, tools and services used, potential gains, and behavior of users, we can design an intuitive, effective, and efficient API. The insights gained from these interviews can also help to validate assumptions and identify new opportunities for product development.