Start with the purpose

We don’t just build an API because it is a fun thing to do. We build APIs to achieve a purpose. They help us or our users solve a problem. This might seem obvious, but let’s be honest: we forget this far too often.

Design is a difficult domain. Perhaps your company has designers (as mine does). Technical people such as testers and developers can sometimes dismiss what designers do as “just making things look pretty,” but the reality is that good design is very hard. Good design makes something that is suited for its purpose. This book is not a book on designs (if you want to read more about the theory of design, check out books such as The Design of Everyday Things by Don Norman). However, if you are interested in good-quality APIs, you need to think for a few minutes about the purpose of your API and how you will design it to meet that purpose.

Knowing that you need to do something is an important first step. Unfortunately, many talks, articles, and books stop there. But what good does that do you? You are convinced that it makes sense to design an API with the purpose in mind, but what is the purpose? What do you do if you don’t know? How do you figure out the purpose of your API?

Figuring out the purpose of an API

You want to figure out the purpose of your API, but how do you do that? There are a few simple strategies that you can use for this. The first thing is to ask questions. If you or your team is writing an API, you were probably asked to do it by someone. Talk to that person! Why do they want the API? What do they want to do with it? What problems do they think it will solve? Ask them these questions and see if you can figure out some of what the purpose of the API is.

Personas

Another simple strategy that you can use is personas. A persona is simply a made-up person that you use to help you think through who might be using your API. For example, you might have a persona representing a user in your company who will be using the API to develop user interfaces, or you might have a persona of a software engineer who works for one of your clients and is using the API to develop a custom application. Thinking through different kinds of users and considering how they might interact with your API will help you understand the purpose that it serves.

When creating a persona, think about things that go beyond just the technology that the person might use or understand. Think about things like the goals and motivations they might have and the things that might frustrate them. It’s also helpful to think of some personal details that might make them a bit more relatable to you. For example, you could think about whether they are a dog person or whether they have kids. Is there some other thing that makes them unique? In other words, what kind of person are they? Writing down details like this can seem a bit silly at times, but it helps you better empathize with this persona, and as you are able to do that, you will be more able to put yourself in their shoes and understand the kinds of things that are important to them. The more you understand this, the better you will be able to understand the purpose of your API.

The why

At the heart of figuring out the purpose is the question of why. Why are we making this API? The why is almost always about solving a problem. A great way to figure out the purpose of an API is to figure out what problem it solves. Does it make it easier to write UI elements? Does it enable clients to customize the application? Does it enable third-party developers to use your platform? Does it simplify integrations with other applications? What problem is your API solving? Answer these questions and you will be well on your way to knowing the purpose of your API.

NOTE:

This exercise of figuring out the purpose of an API doesn’t just apply to new APIs. If you are working with an existing API, there is a lot of value in understanding the purpose. It may be too late to radically alter the design of the API, but there is no more important threat to quality than not actually helping people solve the problems they need to solve. If nothing else, understanding the purpose of an existing API that you are testing will help you figure out which bugs are important and which ones might not matter as much. It takes some skill to figure out which bugs are urgent and which are not, and understanding the purpose of the API helps with that.

Try it out

I have just given you some practical advice, but it won’t do you much good if you don’t use it. This book isn’t just about filling your head with theory. It is about helping you get better at testing APIs. A little later in this book, I will show you some of the tools that Postman has for helping with API design, but right now, I want you to pause and try out what we have just been talking about.

Take an existing API that you have been working on and see if you can write down the purpose in two or three sentences. Use the following steps to work through the process:

1. Identify at least two key stakeholders for the API. Do this by asking the question “Who wants (or wanted) this API built?” Write down these stakeholder names.
2. If possible, talk to those stakeholders and ask them what they think the purpose of this API should be and why they want to build it. Write down their answers.
3. Create preferably two (but at least one) personas that list out the kinds of people that you think will be using the API. What skill level do they have? What work are they trying to accomplish? How will your API help them?
4. Write down what problem(s) you think the API will solve.
5. Now, take all the information that you have gathered and look through it. Distill it down into two or three sentences that explain the purpose of the API.

Once you’ve completed this exercise, you will have a good grasp of the purpose of the API you are investigating. The result of that might look like something like this:

“This API was built so that other services in our company could communicate with our service. It will be primarily consumed by other developers in the company. It is an internal API that will only be accessible inside of our internal company network.

Its purpose is to let other parts of our system know about the status of certain events in our service and so some of the endpoints will be polled intermittently, but overall, it isn’t expected to have heavy usage rates.”

It is important to understand the purpose of an API; however, to fulfill that purpose, an API needs to be usable. Let’s move on to look at what makes a usable API.