OOmnistu

Blog / Engineering Playbooks

Engineering Playbooks

API versioning: how to change your API without breaking your users

Additive vs breaking change, where the version lives, and how pinning keeps integrations safe - with Stripe's monthly-safe, twice-yearly-major scheme as the worked example.

OOmnistu
Reviewed 2026-11-19 · 3 min read

Every API that has users also has a constraint: you cannot change it freely. Remove a field, rename a parameter or change a default, and some client's integration breaks in production. API versioning is the discipline of changing your API without doing that - and it is cheaper to design before you need it than after.

This guide covers the core strategies, then uses Stripe's documented, production-scale approach (from its official docs, checked 19 November 2026) as the worked example.

The decision that matters: additive vs breaking

Most API change is additive: new endpoints, new optional fields, new enum values a client can ignore. Additive change needs no version at all - well-built clients tolerate unknown fields. A version is only owed when you break the contract: removing or renaming fields, changing types, changing defaults or required parameters, or altering error shapes. Teams that version every release create migration fatigue; teams that never version break strangers. The craft is keeping the contract additive as long as possible and batching the unavoidable breaks.

Where the version lives

The mechanism matters less than the pinning model: which version a request actually gets when the client says nothing.

The Stripe model, as documented

Stripe's docs describe a scheme worth studying because it separates two kinds of change. Since the 2024-09-30.acacia release, Stripe ships monthly API releases containing no breaking changes, and twice-yearly major releases (named, like Basil) that can contain breaking changes. Upgrading across monthly releases is safe without code changes; upgrading across a major release can require changes.

Pinning works on several levels. An account has a default API version. Requests can override it per call with the Stripe-Version header. Webhook endpoints take the version set when the endpoint is created - otherwise the account default. Recent client libraries pin automatically: requests sent through a current library align with the API version that was current when that library version was released, so upgrading the library is how you move versions deliberately. The docs recommend matching a webhook endpoint's version to the one your library pins, so events arrive in the shape your code expects.

Three design lessons generalize. First, default-to-safe: an unspecified request gets the account default, so a new release never silently changes a running integration's behavior. Second, make the break window explicit and rare: monthly safe releases mean users are never forced to migrate on someone else's schedule, only when they choose a major. Third, test before committing: Stripe documents using versioning to test a new version in Workbench before upgrading the account default.

Practical rules for your own API

Sources

Drafted with AI assistance from this source. Stripe's scheme is one vendor's current design; verify any specific behavior against its docs before relying on it.