APIs are often built according to the ideas of the API provider without considering the needs and wishes of potential API consumers. Investing time and energy in building an API that no one wants is a waste of resources. It is a big mistake that can be avoided easily. Maybe it is a no-brainer for you, but I have seen this mistake so many times, that I need to make the importance absolutely clear and propose an approach for avoiding the mistake.
If we design APIs as reusable products and design them from the perspective of the prototypical API consumers, then we are on the way to build Consumer-Oriented APIs – APIs that our consumers will love.
I propose to engage with potential API consumers before and during the design of the API and call the approach Consumer-Oriented API Design. So what does Consumer-Oriented API Design mean and why is it so important? What are the implications of it? And how do we do it? You will find out in this chapter.
APIs are Products
To design great APIs, we first need to realize, that APIs are in fact products. APIs are products that are offered on a market to satisfy the needs of a group of customers. This means that APIs are not individually created integration solutions that are tailored for a particular customer and a particular use case. Instead, APIs are designed as generic products for a group of customers. They are intended to be highly Reusablereusable software. In this way APIs can provide solutions to common needs and challenges that are shared by many customers. It may be, that the idea for an API originates from one particular use case for one particular customer, but successful APIs are always more generic. There is always a group of customers, who is interested in solving their diverse use cases with the API.
I like to compare APIs to Lego bricks. The manufacturer usually sells the bricks with an instruction manual, which describes one particular use case, one way of building something with these bricks, let’s say a fire truck. But the bricks are pretty generic: the same bricks can be composed in new ways, that have never been imagined by the manufacturer. So the bricks that were used to build the fire truck, can be used to build a spaceship, castle or racing car.
Why is this possible? It is possible, because the bricks are reusable products, just like APIs. And the bricks are reusable, because they have a simple, clean, clear and approachable interface, just like well-designed APIs.
API Consumers
Great products typically have a great customer experience. They are designed with rigorous customer focus, a deep understanding of the customers and compassion for both the needs and desires of the customers.
So who are the customers of your API? What do these customers have in common? What is a great customer experience for them? And why do they want to use your API?
The customers of your API are the consumers of the API – the developers building API-based solutions. API consumers are developers, using APIs to build other products (e.g. mobile apps, cloud apps) for end users. APIs are never exposed to end-users directly, only to API consumers.
Since the customers of your API are developers, the customer experience should be targeted towards them. So when creating a great customer experience, you in fact need to create a great developer experience! A great developer experience requires an API, that is both functional and well-designed – an API that is easy to use, easy to integrate, well-documented and easy to get started with. In this book we will discuss how to create such well-designed APIs.
The group of API consumers is likely a different one for each and every API you build. So you actually need to figure out the characteristics of your API customer group for each API you build.
You want to look at API consumers as a group, never a single API consumer. Why? Because you want to build APIs as products, with a high potential for reuse by many different consumers.
Consumer-Oriented APIs
API consumers can often choose from a selection of alternative APIs with similar functionality. These APIs are offered by different API providers, meaning that only one API provider “can make the deal” with a particular API consumer. So if the functionality of the offered APIs is similar, how do consumers choose APIs?
Consumers often end up choosing the API that is easy to use, easy to integrate, well-documented and easy to get started with. This means: Your API should be as simple, clean, clear and approachable as possible from the perspective of the API consumer.
But, isn’t this subjective, you might say? What looks simple, clean, clear and approachable from one angle, might not be simple from another perspective. This is why it is important to design and evaluate APIs from the perspective of the API consumers. It is their perspective as customers of the API that matters. So if you as an API provider don’t know the opinion and perspective of your API consumers, you need to figure it out and you need to ask them what it means for them when an API is simple, clean, clear and approachable.
At the same time, keep in mind that APIs are products and should be reusable. They should not be built for a particular API consumer, but for a group of API consumers with similar needs. So ideally, you would ask multiple API consumers.
Building Consumer-Oriented APIs
You probably instantly know, when you have a great API in front of you. But how do you build one? What are the tasks for building consumer oriented APIs?
You need to identify the target consumers, engage with them, get to know their needs and learn about the problems they are trying to solve with the API. This can be achieved by understanding the architecture of the consumers’ solution.
These tasks are described in this section. They allow you to understand the perspective of an API consumer. And from this perspective you can then start to design your API.
Identify the Prototypical API Consumers
You first need to identify the key consumers of your API. Sometimes you don’t know from the beginning who the consumers are, or what they want. Sometimes you might only gradually find out, who the API consumers are and what their needs are. Ideally, you have a pilot group of API consumers that can act as a sounding board for your API design.
But keep in mind, that you develop the API as a product – not as a custom integration solution for a certain consumer. Your goal is to develop a reusable API, that can be used by many consumers in many different scenarios and applications.
To avoid falling into the trap of building a custom solution, it is your task to distinguish between the needs and requirements of a particular consumer and the needs and requirements that the majority of consumers will have. Often it is helpful to construct a prototypical API consumerPrototypical API Consumer from the common needs of the API consumers.
Engage with API Consumers
When people ask me how to design a successful API, I usually ask back: “What do you need to do, so your consumers think that your API is simple, clean, clear and approachable?” Ask your consumers about their preferences. Know your consumers and know their idea of a clean, clear and approachable API. Just ask them. The answers will guide you towards a consumer-oriented API, which is much more likely to become successful. You can run the engagement with API consumers like a classical requirements engineeringRequirements Engineering process. Alternatively, you may use more interactive techniques such as design thinking, to uncover hidden needs, to allow for more creativity and to find unexpected solutions.
Learn about the Solution Architecture of Consumers
It is essential to learn about the solution architecture of your consumers. Become clear on which problems they tackle, which solutions they want to build and what they expect from your API.
The starting point for a consumer-centric API is an analysis of what is needed by the consumers. This might seem quite natural when reading it, but all too often when it is time for designing and implementing, it is forgotten. We need to force ourselves to find out about the needs of the API consumers. This allows us to design an optimal experience for the interaction between the consumer and the API. For the API provider it is thus important to ask: What would the consumer want to achieve by using the API? How can I make it easy for the consumer to find the API? How can I help the consumer to build apps with my API and make it convenient for the consumer to use the API?
What does that mean in practice? The consumers are outside the organization of the API provider, thus the API provider needs to start the design process outside her organization. Only in the last step of this approach, the API provider may make considerations about what is inside the organization: the data formats, and the connections to existing backends. This approach certainly means more work on the side of the API provider, but there is a larger chance that the consumer gets a better API.
Summary
The fundamental idea is to design APIs as a digital product in its own right. Being a digital product, the API needs to be consumer-oriented. Design your API as a product that is reusable by various consumers and in various use cases. You need to know your prototypical API consumers, their needs and their solution architectures. Your API should be as simple, clean, clear and approachable as possible from their perspective, the perspective of the prototypical API consumers. If you design APIs as reusable products and design them from the perspective of the prototypical API consumers, then you build consumer-oriented APIs – APIs that your consumers will love.
Design for the API Consumer
The consumers of an API are the various developers building clients with the API. And the essence of consumer-orientation is knowing the consumers including their needs and desires and putting these needs and desires of the API consumers first when designing the API. We need to know our prototypical API consumers, their needs, and the architecture of the solutions they are building. Our API should be as simple, clean, clear and approachable as possible from their perspective, i.e. from the perspective of the prototypical API consumers. It is important to stress this aspect since internal constraints and legacy systems otherwise tend to dominate API design.
The basis for REST design have been described in detail at other places, so only a short summary is provided here. Let’s read more about the ideas of consumer-oriented API design and the basic design & development approach for APIs.
Design for Reusability
Consumer-oriented design can sometimes lead into the trap of basically designing an API for one customer only, i.e. designing for the very narrow needs of one consumer only. Instead, APIs need to be reusable products that can be reused by various consumers and in various use cases.
Despite being consumer-oriented, a product also needs to be somewhat generic, so it can be used by a wide range of customers. The API needs to be reusable in various solutions.
Complexity
An API solution has a certain complexity. Complexity does not simply go away – it has to be handled somewhere, by someone. Thus, the complexity of the API solution can either be dealt with in the client or in the API.
If the complexity is dealt with in the client, the task of the API provider is simple and the task of the API consumer is difficult. This is usually the result of the inside-out approach and leads to sub-optimal APIs that make the life of the API consumer unnecessarily hard.
If the complexity is dealt with in the API, the task of the API provider is difficult. However, the task of the API consumer is simple. This is usually the result of the outside-in approach. An outside-in approach has a higher chance of producing APIs that consumers love and despite the difficulties for the API provider, it is the recommended approach.