Google, Azure and Stripe version APIs three different ways. Here's what they agree on.

Google, Microsoft, and Stripe version their APIs in three different ways:

• Google (AIP-185): v1 in the path, and never v1.1 or v1.4.2
• Azure: a required ?api-version=2026-01-01 query param, and no version in the path
• Stripe: rolling, date-named versions, and each account is pinned to the version it first called

All three are defensible, and all three agree on one thing: version only when you can't make the change backward-compatible.

Breaking vs. not breaking

✅ Safe: adding an optional field, a new endpoint, a new optional param

❌ Breaking: removing, renaming, or retyping a field, or making an optional param required

Retiring the old version has standard headers

Deprecation: @1688169599
Sunset: Sat, 31 Dec 2026 23:59:59 GMT

Deprecation (RFC 9745) starts the clock. Sunset (RFC 8594) says when it runs out. The sunset date can never be earlier than the deprecation date, and clients should treat it as a hint, not a guarantee.

The full guide compares the four strategies in a table, walks through a 6-step versioning process, and covers how to actually retire a version. Link is in the first comment. 👇