How Stripe Builds APIs

Joyce

July 18, 2022

There is not only one way to become an API-first company. Stripe is a payments company that started as API-first, or more accurately an API-only company. The importance of APIs to the Stripe business continues today. Developer advocate at Stripe, CJ Avilla, shared how Stripe builds APIs, during Postman’s API-first Design and Development training. In this article, let’s review the highlights from CJ’s session.

According to CJ, it’s a naive approach to take internal APIs, and then sanitize them in order to release them to the public. Instead, it’s important to consider all potential downstream impacts while designing new features. In CJ’s session, he shared tactics used by the Stripe engineering team throughout each stage of their API lifecycle.

Stage 1: Talk to customers

The API development process at Stripe is influenced by the company’s history and culture. For example, Stripe has a strong organizational culture of gathering the voice of the customer and uses several tactics to gain empathy for the users and learn about their needs.

What we’re calling API-first [today], at Stripe, we call it developer-first because we’re building for developers

CJ Avilla, developer advocate at Stripe

1. Pair programming: the “Collison installation” was a tactic employed by Stripe’s founders to gain their earliest users at Y Combinator. The Collison brothers would sit down with all the other incubator companies as they tried to implement Stripe in their own applications. In doing so, they uncovered new insights during their pair programming sessions.
2. User research: Stripe also performs structured user experience research (UXR) to answer questions like “What challenges do developers face when using our API reference docs?”. They record the developers trying to integrate using the Stripe API to pinpoint areas of friction and identify unforeseen scenarios.
3. Exposure hours: Development teams spend time, called exposure hours, with developers to better understand how they plan to integrate with your API and how they are solving the problem today, even without your API or new feature. Exposure hours can be gained watching videos or attending livestreams.

Stage 2: Design and review

Stripe also has a strong writing culture. It’s not unusual to circulate 20-page design documents proposing new changes during an API review. They follow a rigorous documentation process to preserve tribal wisdom that might otherwise be lost.

1. Governance team: a review board is staffed with engineers from across the organization. This team establishes guidelines for Stripe APIs, and also reviews designs and proposals for any releases that have potentially public-facing impacts.
2. Gavel blocks: stakeholders impacted by the change are listed at the beginning of design documents next to a checkbox, to indicate whether the document has been reviewed and to note any concerns and comments. Debates can continue asynchronously threaded in the document, or get hashed out in a virtual meeting.
3. Changelogs and tradeoffs: Besides tracking changes, the team thoroughly documents all potential downstream impacts. Perhaps most importantly, the team outlines the thought process behind their decision-making process, weighing the tradeoffs with each possible option.

[In the design document], we’ll outline all the different options that we considered, and why we chose not to do each of these different options. This gives you tons of clarity when you have some final decision.

CJ Avilla, developer advocate at Stripe

Stage 3: Implementation and release

The Stripe team implements and releases public API updates several times a day, and automates testing as part of their CI/CD pipeline.

1. Validation in CI/CD: tests are run in CI/CD to ensure certain steps are completed, such as generating the OpenAPI and client libraries, prior to releasing any public changes to the API.
2. Custom generators: the Stripe team doesn’t use OpenAPI to design their API. Instead, they rely on OpenAPI to automatically generate assets that were previously updated manually. There are certain features within their API that are not natively supported by OpenAPI. And so, they create custom, internal solutions to generate assets that would otherwise be maintained manually, artifacts such as their Postman Collection, mock servers, SDKs, and documentation.

Check out the Stripe Postman Collection in the Stripe Developers public workspace: https://www.postman.com/stripedev/workspace/stripe-developers/overview

Stage 4: Deprecate

Stripe does not deprecate public APIs. The expectation is for integrations built over a decade ago to continue working seamlessly with each new update.

Watch the full talk

Check out “How Stripe API Features Land” in CJ’s own words, and watch until the end for a sneak peek at never-before-seen internal tooling at Stripe.