API Versioning and Deprecation Policies

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

## TL;DR

API versioning and deprecation policies tell agents whether a failing integration broke because the contract changed, the client pinned an old version, or a sunset window expired.

## Core Explanation

Agents troubleshooting integrations should collect the requested API version, SDK version, response headers, changelog entries, preview feature flags, webhook version, and deprecation notices. A request can fail even when credentials and payloads are correct if the client is speaking the wrong contract.

Deprecation handling is also an evidence problem. Agents should prefer official versioning docs and changelogs over guessing from error strings. The right recommendation may be to pin a version, test a new version, migrate a removed field, or stop using a preview endpoint.

## Source-Mapped Facts

- GitHub REST API documentation states that breaking changes are released in a new API version. ([source](https://docs.github.com/en/rest/about-the-rest-api/api-versions))
- Stripe API documentation describes overriding the account default API version by setting the Stripe-Version header. ([source](https://docs.stripe.com/api/versioning))
- Google AIP-185 defines API versioning guidance for Google APIs. ([source](https://google.aip.dev/185))

## Further Reading

- [GitHub REST API Versions](https://docs.github.com/en/rest/about-the-rest-api/api-versions)
- [Stripe API Versioning](https://docs.stripe.com/api/versioning)
- [Google AIP-185 API Versioning](https://google.aip.dev/185)