API Design is about empathy

What is an Application Programming Interface? How do you manage, govern, and improve the APIs in your business? An internal developer platform enables faster iteration of new APIs for experimentation of new business models. This article is not about external API programs serving developer experiences like Stripe or Shopify. I will not cover anything related to building or supporting external facing platform businesses.

The term API is overloaded. In the context of this article, it means synchronous RESTful APIs served over HTTP that enable customer experiences. There are several API Paradigms. They have their use cases in business. The APIs I am discussing are building blocks of data and function. They enable the creation of new business models and customer experiences. APIs are promises of functionality. Once in use by customers, they are hard to change and migrate to new versions.

If you read nothing else, take away these three points.

  • APIs are building blocks that are hard to change
  • API-First design is essential
  • Have Empathy for future users of your API

What is an API?

APIs are building blocks of functionality. If I want to build a new experience, like a store, I need data. As my business grows, I want to add more and more functionality powered by more APIs.

“The whole reason APIs exist is to support integration.”

2020 State of the API Report from Postman

Before I dive deep into what APIs mean in business, I want to share this Postman report on APIs. The high-level report details are here. Nordic APIs has a summary as well. I will share a few of the highlights that stood out to me. APIs are essential for digital transformation initiatives. Nearly a third of respondents said APIs played a role in responding to COVID-19. 60% of respondents rate themselves a five out of ten in pursuing an “API-First Design” philosophy. Though I will warn the survey takers were not aware of a standardized definition of the term. What is API-First Design?

API-First Design

API-First Design is important because it emphasizes thinking about how your users will interact with the API. It also emphasizes making the result more reusable and consistent. The purpose of an API is to act as a reusable building block. Once an API is in use, it is hard to change. You want to get it right from the start. The temptation for many developers is to start with code first. That is fraught with peril since we never seem to have time to write the specification. It will be wrong or out of sync forever. Let me tell you about a company that focuses on making APIs that users love.

The Stripe API Evolution Story

Stripe is well known for offering APIs that developers love to use for payments. Michelle Bu tells the story of how the Stripe API evolved over the years. Stripe evolved its API to offer a unified API experience through significant thought, effort, and design.

To sum up their challenge, they had a simple experience people loved. Stripe supported more payment methods that became hard to offer support for and developers to use. They created new concepts called PaymentIntents and PaymentMethods.

“The design of a set of APIs that would work across all payment methods globally with a single integration was the hard but fun part… launching a new API that replaces a foundational, established API doesn’t stop at just writing the code to spec—rolling out this change took almost two years.”

Despite this achievement, there was more work to do. This unification came with extra complications for their users in adopting the new concepts.

“The hardest part of realizing the PaymentIntent migration was not a technical challenge, but a perception challenge: The new APIs didn’t feel like “seven lines of code” anymore.”

Their next challenge came from designing a user experience to encourage the usage of their unified payment concepts.

“Our ultimate solution to this problem was to add a convenient packaging of the API… We called the default integration the “global payments integration” and named the new integration “card payments without bank authentication.” We put the implications of this integration front and center in the documentation: with this simpler flow, you won’t be able to easily add new payment methods.”

“Keeping things simple means making sure your APIs are consistent and predictable—and that you’re creating the right packages to gradually reveal the power of your API as your users need it. It also means not underestimating your user. It’s tempting to abstract away too much in service of “keeping things simple,” but users will often quickly discover that they need more control.”

Michelle closes out her story with gratitude. There were many others on the periphery that supported the journey of Stripe’s API.

In the story, Michelle shares three steps to take when rethinking your API

  • Consider real-life integration scenarios
  • Question everything about existing APIs
  • Include people that are the experts in the business domain

Target’s Journey of API Management and Developer Centricity

Jay Dreyer shares the journey Target took for managing its APIs. At first, it was the wild west. Teams did as they liked. Over time Target began to put in place standards across the organization to ease the burden of inconsistency and waste. Target bought an API Gateway technology and hoped its implementation would lead to better contract management. It did not. Specifications and APIs drifted apart. Target decided to build their API gateway and mandated usage by their teams.

Target wants consistent cataloging and management of individual APIs across software teams. This journey started with simple but hard to answer questions. Who is the owner of the API? What is the lifecycle status of the API? When something breaks, who is the contact person? How long has the API existed? Before teams could publish their APIs in the API gateway, their specification would need to go through a formal review. For their 1000s of APIs, it made sense over time to automate verification of the API specification. Jay mentions a familiar experience, teams wanting to use a wacky name for their service. ‘Teams change. Marketing changes. What’s served does not change.’ You will regret years down the road names you thought once were funny. Jay mentions that there are more challenges to solve for the Target API program. It is still difficult to verify the running API is adhering to its promises in the specification or teams are updating the specification.

I share this story because it illustrates that API strategy is not about one person or team or buying a tool. API enablement in a business is a primary focus to build and refine.

API Design as Design

Design. This word keeps showing up without a clear definition. What is design?

“The essence of design lies in the process of discovering a problem shared by many people and trying to solve it.” - Designing Design, Kenya Hara via.

It might be easy after reading these transformation stories to gloss over the difficulty in creating APIs. Creating an API contract is design work. Lars Trieloff of Adobe writes, there are three principles of API-First Design.

  1. Your API is the first user interface of your application
  2. Your API comes first, then the implementation
  3. Your API is described (and maybe even self-descriptive)

Alvaro Videla believes we should leverage empathetic design in the creation of our APIs.

“By viewing our work with fresh eyes and asking more questions than we provide answers, we can create APIs that empower our users to become designers themselves.”

Alvaro highlights insight from several designers and relates it to API development. Expect your API design to evolve through its use. Your API’s design will communicate to its consumers what is and is not possible. As time passes, you can make your API more intuitive, the design never seems done.


Embracing APIs in your organization starts with the people. I did not cover much of the actual technology pieces of the puzzle in depth. Building an API is hard! There is versioning, backing infrastructure, testing, and many other challenging aspects. I hope that you are reading this and thinking that making APIs a first-class citizen in your business is critical. In the future, as I learn more, I hope to write about the technologies that make this transformation easier. Before you go, remember these three things.

  • APIs are building blocks that are hard to change
  • API-First design is essential
  • Have Empathy for future users of your API