API Versioning and Deprecation

Status: public · Confidence: medium (0.865) · Basis: verified_sources

## TL;DR

API versioning and deprecation define how an API changes without surprising clients that depend on existing request, response, authentication, or event behavior.

## Core Explanation

Good API versioning separates compatible evolution from breaking change. Compatible changes can add optional fields or endpoints. Breaking changes require a version boundary, migration guide, sunset timeline, observability for affected clients, and a communication channel that reaches integrators before behavior changes.

For developer infrastructure, versioning is also an agent-readiness issue. Agents inspect API docs, call SDKs, and debug failures. Clear version labels, changelogs, deprecation headers, and migration examples make tool use safer and reduce brittle automation.

## Source-Mapped Facts

- Stripe API versioning documentation says major releases can contain breaking changes while monthly releases contain only backward-compatible changes. ([source](https://docs.stripe.com/api/versioning))
- Google AIP-185 requires API interfaces to provide a major version number. ([source](https://google.aip.dev/185))
- RFC 8594 defines the Sunset HTTP response header field for communicating that a resource is expected to become unresponsive at a specified time. ([source](https://datatracker.ietf.org/doc/html/rfc8594))

## Further Reading

- [Stripe API versioning](https://docs.stripe.com/api/versioning)
- [Google AIP-185](https://google.aip.dev/185)
- [RFC 8594](https://datatracker.ietf.org/doc/html/rfc8594)