Don’t start with your API, start with your customers

API design is multi-dimensional, requiring you to consider both the business and the technology dimensions. Product management principles and techniques can help you juggle how an API is designed in both dimensions, so you don’t get lost in the weeds of just the technical aspects. But when considering the business benefits of an API, where exactly should you start?

I recommend to focus. First look into one particular aspect of business design for your APIs, and get a clear picture of the people who will use your API. In my opinion, the best place to start your API design is with the people. I realize this may seem counterintuitive because, after all, the API is a machine-to-machine interface that operates seemingly without human interaction. But think about it: there are people and organizations on the other end that will consume the API.

Know your API customers

In the API economy, API consumers are your “customers,” and their collective opinion will determine the success of your APIs. APIs should never be built for internal stakeholders – the product owner, the project manager, or the employer. They should always be built for customers. 

Start any new API product, project, or design by digging into three areas to understand these customers:

• (1) who they are;
• (2) what needs they have, what circumstances they face, what tasks they want to perform, what pains they have, and what benefits they would appreciate;
• (3) how an API can fulfill their needs, improve their circumstances, help perform their tasks, relieve their pains, and create real benefits for them. 

The first two points help to build an understanding of the market for your API, which consists of customers and their needs. Only with this market understanding as a basis can you tackle the third point and construct APIs that satisfy the needs of the market, and achieve product-market fit. 

Who are the customers of your API?

API consumers are the people or organizations that call the API and profit from its benefits. They are the customers of your API.  And if your API does not exist yet, these are the prospective customers of your API. Don’t fantasize about them – get to know them! 

“If you build an API without having thought about the customer, you are definitely doing it wrong. If you build an API without having talked to a customer, you are very likely doing it wrong.”

Developing empathy with API customers

It is essential to get to know the prospective customers of your API, so you can make design decisions that are in their best interest, and thus create APIs they will like and appreciate. You will need to develop empathy and understanding for these customers and their challenges. In this context, empathy is the ability to think from your customer’s perspective. It is also described as “wearing the shoes of the API customer.” If you have developed empathy with your customers, it gives you a sixth sense of their needs, wants, and likes so you can construct APIs that are useful and usable, and that have differentiators that truly delight your customers. 

You cannot develop empathy by thinking about your customers or their needs by yourself in the confines of your office. You develop empathy by engaging in a dialog with them, which means you will need to go to where they are. Get outside the office to talk to them in person. Focus on listening, learning, and understanding. 

Create Customer Profiles

Write down what you know or assume about your API customers in a customer profile. When you start looking in detail at them, you will notice that they are not a homogeneous group. API consumers can have different roles in their organization: they can be developers who actually write the code that calls the API, but they can also be business or product managers looking to build a digital product that calls the API.  Maybe there are also API consumers from different industries, countries, or backgrounds. You may need to create several customer profiles, where each customer profile represents a group of customers (not a single customer!). Pick a reasonable set of personas (maybe 2-3) and try to make a profile for them, so you get a realistic “feel” for who they are and what is important to them. 

List relevant tasks of the customer

The customers of your API have a reason for being customers: They are struggling with pain points while performing a specific task. Your goal is to position your API to be the one thing that can relieve their pain.

Some people tell me this approach is sneaky. But I don’t agree. If the API really solves a problem and is useful, then this approach is not sneaky but efficient (and helpful).

In his book The Innovator’s Solution, Clay Christensen introduces the idea that people “hire” your products to get a job done. The better you understand the job they need to get done, the better of a product you can build. Surprisingly, Christensen found in his research that customers do not always use products as originally intended by the product team. This is because the product team did not have an adequate understanding of the circumstances, tasks, and needs of the customer. Products could be built and optimized more effectively if we knew for which tasks people wanted to use them.

This mistake is common in APIs as well. Learn from the mistake and properly analyze the tasks your API customers try to accomplish.

Describe the customers’ pains and gains

You need to develop a deeper understanding of the pains and gains of the API customer. Pains are limitations, constraints or challenges for the customer with regards to performing his jobs and tasks. Gains are benefits or boosters that help them achieve the job. Pains and gains function as motivators for the customer to change something and search for a solution. The stronger the motivators, the easier it will be for you to place your API products as the solution for the customers’ pains. 

If there is enough interest on the side of the prospective customers, conduct a workshop with them, where you discuss pains and gains of their current situation. You can collaboratively sketch potential solutions and discuss them. 

And in case you already have an API, study the usage data and logs to find out how your current API customers actually use it. Are there a lot of 400-type error codes? Your API might not be understandable, unintuitive, or complicated. Talk to the customers to understand their exact pain with the API. Does the data show that you only have very few customers, or do the customers only use a few API calls? It might be a sign that your API is being used, but not being useful. The solution? Talk to your customers.

Order your thoughts on the API Value Proposition Canvas

If you diligently apply this approach (understanding who your customers are and what needs, pains, and gains they have), you will end up with a wealth of information, that you may want to process in a structured form. The goal is to generate insights, by processing, comparing, filtering, and evaluating the data. Some judgment needs to be involved in this step.

A great way to visualize the information is the “Value Proposition Canvas” from the book Value Proposition Design by Alex Osterwalder et. al. In the figure below, we have adapted it for APIs.

The API Value Proposition Canvas provides a structure to describe an API customer profile (the circle on the right) and a matching API product (the box on the left). You fill it out as follows:

(1) note the jobs or tasks to be done by the API customer in the circle on the right

(2) add the potential gains and pains with regards to these jobs, and note them in the circle as well 

(3) construct the API product that realizes gains and relieves pains in the box on the left side. See more details on this step in the next sections.

It’s an investment

“All this work and I am not even writing any OpenAPI specs, yet?” Yes, I hear you! But have patience. Isn’t it better to spend a bit more time in the beginning, to minimize the risk of building APIs that no one wants? It’s like studying the map before you leave for a road trip, or sharpening the saw before you cut a tree. It is an investment that will pay dividends in the final step: constructing an API.

Finally: Construct your API for product-market fit

Why did you create all of these insights about customers? These insights help you understand in detail what type of API could be useful for the customer. Based on this data, you can propose an API that you can confidently say will help customers do a job they need done. You can propose an API that creates value by taking away some existing pains that the customers said they had right now. You can propose an API that helps the customers realize some gains that they wished they could realize. 

By starting with the customer, you can follow a customer-centric approach, and with a laser-like focus, you can construct an API that by construction fits the needs of the customers, i.e. the market (assuming your analysis was correct). The approach ensures by construction what we call product-market fit.

In the usual technical API design approach, APIs are proposed based on technical design decisions alone, the customer insights and needs are not a direct input to this process. It would thus be a coincidence if the API that results from this process would fit with the customer’s needs. 

The approach described here is the opposite: the API is constructed from the outset to fit the customer’s needs. In the words of Steve Jobs: “You have to start with the customer experience and work back towards technology, not the other way around.” By starting with the customer needs, and using them as a guide for the API design, you increase your chances of proposing a useful and successful API. 

In the next blog, I will tell you about some typical stumbling blocks when people apply this approach in practice. Know them and have a smoother journey into the API economy. Stay tuned.