How API changes flow into Stripe's developer products

Summary

Stripe describes how API changes are propagated across its developer-product suite, including SDKs in seven languages and three release channels, the CLI, Shell, API Explorer, API Reference, changelog, and internal tools. Historically, v1 workflows used OpenAPI or a Ruby-based DSL while v2 APIs used protobuf-based DSLs and an internal API specification, forcing teams to maintain parallel generators and leaving some products without v2 support. Stripe chose OpenAPI as a shared representation and built a pipeline whose generated artifacts are tailored by variant, release phase, and API version, with vendor extensions carrying Stripe-specific metadata. Automated validation, OpenAPI diffs, pre-release comparisons, versioned snapshots, and downstream publishing now connect API definition changes to documentation, code samples, SDK and CLI releases, while older v1 versions remain difficult to regenerate with newly added metadata.

Takeaways

1. 1

   Generated OpenAPI artifacts are tailored by variant, phase, and version so public products can exclude private APIs, preview products can include appropriate release phases, and consumers can request a specific API version.

2. 2

   In v2, API changes are stored and reproducible from the beginning of history, allowing canonical OpenAPI descriptions to be generated for past or current versions; v1 cannot yet regenerate older versions with newly added metadata.

3. 3

   API changes are checked before merge for naming, types, compatibility, documentation, and product-specific constraints, then reviewed through OpenAPI diffs and enriched pre-release comparisons before downstream releases.