How to craft a great, measurable developer experience for your APIs

I often hear the phrase “API as a Product” when talking to companies who have built successful API programs. A play on the “Software/Platform/Infrastructure as a Service” monikers, they’re basically saying, “We treat our APIs just like we treat other products that we offer (mobile app, website, or any physical device).” For any product, it’s important to understand who you’re building it for, what they are hoping to accomplish, and how they are doing it right now.

Subsequently, once you have built a product, it’s paramount that you look at the following things to ensure its continued success:

• How you make your product discoverable to potential users and customers

• How you onboard users onto your product

• How you analyze usage patterns, recognize feedback, and iterate to continuously improve your API

Great products are about great user experiences. Developers, the primary users of APIs, benefit hugely from a thoughtful UX. A positive developer experience (DX) that makes an API more approachable, usable, valuable, and sticky can transform it from being just another functional tool into an empowering asset. When a developer is using an API, they’re essentially delegating a job to that service. Sometimes, they’re paying for that job to be done. This brings home the need for a great DX because, like any other product, it is one of the ways in which we choose between similar products.

In this blog post, I’m going to talk about crafting a great developer experience for your APIs. I’ll share some stories as I introduce four useful metrics (because where’s the fun without data!) that I have seen companies adopt in their successful API journeys.

Metric #1: Bounce Rate

Back in 2017, I went to an API conference where I met a Google product manager who introduced me to a metric that he was obsessing about for his API: Bounce Rate. I was familiar with this metric in the context of website analytics, but what does it mean for an API?

He (philosophically) defined Bounce Rate as a developer coming to your API portal, investing the time to generate authentication credentials (filling out forms, verifying emails, etc.) but then failing to make a single successful call against your API. Essentially, your API’s Bounce Rate is the number of generated API tokens that are not used to make even a single successful API call against a dimension of time.

After he started measuring this metric for a rather popular API whose success he was overseeing, he was surprised to see how high this number was. From then on, improving the API’s Bounce Rate had become an essential part of his team’s OKRs. Since I heard this story, I have asked this question of many API owners across companies who have been amazed to find out that their API’s Bounce Rate was sometimes as high as 40-50%.

(I’d be remiss if I didn’t point out the “successful” qualifier here that the Google PM had adopted measured through a 2xx response code. The number is often worse if you remove that qualifier, and it’s an important metric to analyze independently.)

Imagine this: you have painstakingly, carefully built this API, somehow convinced users to come to your API portal (topic for another post), convinced them to try your solution, and convinced them to go through the arduous steps of generating the credentials—but they ultimately failed to make a single successful API call. Not even one measly “Hello, world!” call. Why?

Here are three prominent reasons that I have observed both firsthand and in research:

1. Users couldn’t figure out how to use the authentication credentials. (Auth is hard; cURL what?)

2. Users couldn’t figure out where to start. (The “reference manual” documentation is overwhelming!)

3. Users were not comfortable using an API directly. (Give me a UI!)

Let’s go back to our “API as a Product” moniker for #1 and #2.

Good product teams often disambiguate between designing for first-time user experience (FTUX) and designing for continuous user experience. FTUX is where the user’s first impressions are formed, and the stage for a positive long-term relationship is set. Continuous user experience assumes some familiarity from users who are past the initial learning curve, and it aims to ensure the product remains relevant, useful, and enjoyable for users as their familiarity and expectations grow. In other words, this is the difference between optimizing for someone experiencing or learning how to use your product for the first time vs. helping someone who already knows how to use it.

Yet, API documentation on developer portals is often more like receiving a “reference manual,” where the onus is on you to figure out how to take the first step. They’re anchored more in being “correct and comprehensive” than helping you form the right first impression that will lead to a beneficial long-term relationship. I struggle to remember the last time I truly enjoyed, over a longer-term horizon, a physical/mobile/web product that didn’t guide me through a phenomenal first-time experience.

Related: Simplifying API documentation for a great first user experience

Enter Postman. Postman was introduced to the world 12 years ago, in this now-infamous Stack Overflow answer from our co-founder and CEO, Abhinav Asthana. Today, more than 30 million developers have used Postman to make API requests across as broad a variety of APIs as you can imagine. That’s more than 30 million developers in more than 500,000 organizations all around the world—all who use the Postman app and understand how it can be used to successfully call your API.

At Postman, we understand that authentication is hard. We’ve had developers tell us that for the last 12 years. In addition to simplifying authentication for API consumers within Postman, we also launched easier API authentication for API publishers in 2023. Any API publisher can now register their API within the Postman Public API Network and make it “click-through easy” for any Postman user in the world who is trying to call their API, joining the likes of OpenAI, Notion, Twilio in the process.

Let’s further address #2, “Users couldn’t figure out where to start.”

I’d like to introduce a key artifact that developers create with Postman—the Postman Collection. There are more than 100 million active Postman Collections in the world. Postman Collections are executable documentation for APIs and API workflows, designed for sharing. With a collection, you can design your documentation for execution, with the specific intent of getting your prospective user to make their API calls successfully. You can bundle in authentication helpers, combine reference documentation with Getting Started guides/recipes, or just create a simple, actionable way to help the user start using your API.

The WhatsApp team over at Meta has done a fantastic job of this, using Postman Collections to encapsulate the reference documentation with Getting Started guides for their users. Each part of the onboarding experience was thoughtfully designed and optimized for users to actually use the API.