How to Product Manage for APIs

When we think about software, what we imagine is based on our own user experience, consisting of the interface, buttons, and words that we can interact with. Meanwhile, we are all aware that the interface is merely the tip of the iceberg beneath which lives the magic between our devices, applications, and internet connections that make the interface function. Often, a key part of that experience is one or more application programming interfaces, more commonly called APIs.

An API, in short, is a bridge between different software systems to help them talk to each other and exchange information. Most of the software I’d product managed in the past was built with a focus on end users — human end users I could talk to in order to determine whether the software was working. Recently, however, I began managing the delivery of an API — a product that works between machines rather than people. I had to ask myself: What’s the best way to assess needs and functionality and judge success for something you cannot talk to? Here’s my advice on the particular set of challenges of API management.

What is an API?

I think of an API as a waiter at a restaurant. The person waiting on your table does the job of communicating between you, a person visiting the restaurant, and the people in the kitchen to make sure your order is prepared and delivered correctly. 

It goes without saying that when you visit a restaurant, you probably want only one entrée, not the entire menu. The kitchen, meanwhile, has the ingredients to prepare a much larger number of set dishes. Part of the server’s job is to broker that interaction. First of all, they prevent you from making errors. If you try to order something that’s not on the menu, then they will correct you and ask you to try again, reiterating what is available. Similarly, when the kitchen prepares your meal, the server makes sure that it is actually what you ordered. If you order the pasta and the kitchen makes you a burger, the server will send it back to them before it hits your table. The bridge and the gatekeeper between those worlds make those interactions possible.

And so it is with APIs between systems. One system needs to send a request over to the second system. The job of the API is to make sure that those systems play nicely together then and will continue to do so for years to come.

Define your characters

An important step in managing an API is collecting requirements from the key users and systems you are serving. Some APIs form a bridge between two systems, and others are built to open one particular system to many.

Consider building a table mapping out that system of user stories to include the full context of needs and capabilities. Think of them as separate characters with their stories. Collect the jobs to be done and the context for each system and user:

For each of these five characters, list out:

• Jobs to be done: What do they need to accomplish in this interaction? What are their goals?
• Capabilities: What can they actually do?
• Constraints: In what ways are they limited in serving other parts of the system?
• Upcoming changes: How will needs for these systems evolve over time?
• For the systems: What are the possible endpoints that the API can connect to? Should any new ones be created? Is one system writing information to another only, or are the changes bi-directional?

The results of this exercise will be different for every set of systems that you build for, and it is important to build a full picture including the intent and context of user interactions. This will set you up to understand where the API sits within the system and what it needs to accomplish. 

Prioritize the build

Just as with other products, once you have the needs and functionality mapped out for your API product, it is important to prioritize the order of your build. 

To do this, look at your systems map and find the endpoints and functionalities with the highest risk. This means finding the parts of the API product where, when not working as expected, cause all other parts of the experience to come to a stop. This could be the payment function (critical failure), an inability to sign in (oops), or another pivotal point which causes dysfunction on either side of the API.

You may also want to prioritize areas with the most uncertainty. When integrating multiple systems, engineers often discover attributes of solo systems they wouldn’t have noticed otherwise. Do your best to expose that uncertainty early. When asking your engineers for their level of familiarity with the systems that they’re building for, you can use the 80/20 certainty method: Ask them if they are 80% certain that the connection will work or if they are 20% certain. This leaves space to uncover areas that may require further learning, so you can prioritize those risks to delivery up front.

Get testing

It is important to have a way to check that endpoint connections are working as expected. Whether you are using a well-established tool like Postman or you have another in-house method to run test API calls and see their responses, be very clear about your methods for testing every endpoint and allow time in the project to do this work. This is essentially your replacement for human user interviews where you can ask, “Is this working for you?”

Document every decision

Documentation is critical to maintain a healthy API. Developers building into your API need to be able to clearly read how they can interact with it, and there are so many APIs out there with endpoints of mystery floating around. Document every single decision that was made and how it related to the health and capabilities of each system. Do yourself this favor both for other people and for yourself in the future.

Write the story of the system

If you are a Product Manager who’s found yourself in charge of an API, remember that systems themselves are like characters with their own needs, capabilities, and constraints. Write the story of those specific “system personalities” and get to know them. Define what correct functionality looks like and work with your engineer to map out points of highest risk. Build system tests to ensure that each of those risks has been addressed, that functionality has been validated, and that minimum functionality is in place even under less than ideal circumstances.

It’s a lot of work, but once it’s completed, you will make the unseen appreciated by adding functionality to multiple applications that were never built to be friends, adding value to every system.

Sarah Cassidy (she/her) is a Senior Product Manager at Postlight. Interested in working on your product? Get in touch.

Work for Postlight! Love making exceptional digital products? We’re hiring engineers, PMs, designers, and strategists. Let’s grow together. See openings.