An API version groups compatible API operations and promises continued compatibility with client applications. Providers use versions to manage evolution when new features, enhancements, or fixes might otherwise force client changes. section 4.6
A backward-compatible change can enter an existing version; a breaking change usually requires a new version. This avoids coordinating an incompatible release simultaneously with every consumer, while adding the cost of maintaining older versions. section 4.6
API versioning decisions include:
- Set a release and support schedule so consumers can test and migrate between stable versions; one cited schedule releases every three months and supports versions for at least twelve months. section 4.11.3
- Choose an identifier format such as SemVer, CalVer, or a stability label. section 4.9
- Use pinned versioning to associate a consumer account with a default version, then allow upgrades or per-request overrides. section 4.7.6
- Document breaking-change, deprecation, and sunset policies, including whether planned sunsets should fail automated breaking-change checks. section 4.11.3
Pinned versioning with Stripe
If a consumer’s first Stripe request occurs while version 2022-11-15 is current, later requests default to that account-pinned version. The consumer upgrades through the account profile; the /v1/ path segment exists but is not actively used for this setting. section 4.7.6
Figure 4.7 API deprecation and sunset dates. After the deprecation date, an API isn’t recommended for use. But after the sunset date, the API is unavailable.
Use the deprecation-and-sunset timeline to distinguish the period when an API is discouraged from use from the date when requests become unavailable. section 4.11.3
