Examples of deprecating an API version: 3 practical examples that actually work

API versioning advice is everywhere, but real examples of how teams actually deprecate and shut down versions are harder to find. The theory says: announce, warn, migrate, remove. Reality says: you’ve got enterprise customers on legacy SDKs, forgotten cron jobs, and dashboards that nobody wants to touch.

That’s why this article leans heavily on examples of deprecating an API version: 3 practical examples from widely used platforms, plus several supporting cases:

• Stripe’s date-based API versions and slow, predictable deprecation.
• GitHub’s header-based versioning and multi-year removal windows.
• Google’s aggressive sunsetting of older cloud APIs with hard deadlines.

Around those, we’ll layer in real examples from Twilio, Slack, and AWS to show different strategies for communication, migration tooling, and enforcement.

Stripe: a gentle, date-based example of deprecating an API version

Stripe is one of the best examples of deprecating an API version without panicking developers.

Instead of v1, v2, v3, Stripe uses date-based versions (for example, 2024-09-30). Each account is pinned to a version until it explicitly upgrades. This design changes the shape of deprecation entirely.

Here’s how their pattern works in practice:

• Version pinning per account: When you create a Stripe account, it’s locked to a specific API version. That means Stripe can ship new features and breaking changes without instantly breaking your integration.
• Non-breaking behavior for old versions: When they introduce a breaking change, they gate it behind the new version date. Old versions keep the old behavior.
• Soft deprecation via documentation and dashboards: Older API versions don’t vanish overnight. Instead, Stripe marks them as “out of date” in dashboards, SDK docs, and changelogs, nudging developers toward newer versions.

A concrete example of deprecating an API version at Stripe:

• Stripe introduces a new parameter for payment methods and changes the default behavior.
• The change is breaking for some edge cases.
• Stripe releases the new behavior under a new API version date.
• For months (often years), older versions keep the prior behavior.
• Stripe emails affected accounts, adds upgrade guides, and surfaces warnings in the dashboard.

This is a slow, account-by-account style of deprecation. You don’t get a single global shutdown day like “v1 dies on June 1st.” Instead, you see a long tail of gradual migrations.

If you’re designing your own strategy, this is one of the best examples of deprecating an API version without big-bang cutovers:

• Use per-tenant versioning where possible.
• Treat deprecation as a nudging process, not a single event.
• Make the dashboard and logs do the heavy lifting: warnings, upgrade hints, and sample requests.

For a taste of how mature API providers manage long-lived versions, it’s worth browsing Stripe’s public API changelog and upgrade guides.

GitHub: header-based versions and long deprecation windows

GitHub’s REST API is another strong example of deprecating an API version with a long runway and obsessive communication.

Instead of URL-based versions, GitHub often uses media type versioning via the Accept header. For example:

Accept: application/vnd.github+json; version=2022-11-28

Here’s how their deprecation playbook typically runs:

• Announcement with exact dates: GitHub publishes a deprecation notice with three key timestamps: announcement date, sunset date, and actual removal date.
• Deprecation headers: Responses from deprecated endpoints include headers like Deprecation and Sunset, giving automated clients machine-readable dates.
• Fine-grained removals: Instead of killing a whole version, GitHub often deprecates specific fields, endpoints, or behaviors.

A real-world example of deprecating an API version: 3 practical examples from GitHub’s history includes:

• Deprecating legacy authentication methods (such as password-based auth) in favor of tokens.
• Retiring older preview APIs once they become stable.
• Removing outdated webhook payload fields that duplicated newer, better-structured data.

GitHub’s approach is especially useful if you:

• Can’t easily pin versions per account.
• Need to support multiple API shapes in parallel.
• Want clients to discover deprecation status programmatically.

If you’re designing your own sunset strategy, GitHub’s style gives you one of the best examples of:

• Using HTTP headers to communicate deprecation.
• Publishing clear timelines and keeping them.
• Deprecating capabilities rather than monolithic versions.

For a broader view of web API deprecation and HTTP headers like Sunset, the IETF draft on the Sunset HTTP header field is a useful reference.

Google Cloud: hard deadlines and aggressive clean-up

On the other end of the spectrum, Google Cloud often provides hard, non-negotiable end-of-life dates for older API versions. This is one of the clearest examples of deprecating an API version when you absolutely must shut it down for security, cost, or architecture reasons.

A typical Google Cloud deprecation pattern looks like this:

• Public deprecation announcement on the product’s release notes and support pages, often 12–24 months in advance.
• Customer impact analysis for large accounts, sometimes with direct outreach from account managers.
• Migration guides and tooling, sometimes including automated migrations or side-by-side compatibility modes.
• Hard shutdown date, after which requests to the old version return errors.

Real examples include:

• Older versions of the Google Cloud Storage JSON API being retired in favor of newer, more secure versions.
• Legacy Google Maps APIs being shut down and replaced with the newer Maps Platform APIs.
• Deprecated machine learning APIs being consolidated into Vertex AI.

This is a textbook example of deprecating an API version when you can’t afford to run the old stack forever. The tradeoff is obvious: you get a cleaner, more secure platform, but you’ll need to manage a spike of migration work for lagging customers.

If you operate in regulated sectors—finance, health, government—this style might be closer to what you need. For context on long-term technology lifecycle planning, the U.S. Digital Service and related federal guidance on tech modernization (for example, via GSA.gov) can be a useful backdrop when you’re justifying deprecation timelines internally.

Beyond the big three: more real examples of deprecating an API version

The headline promised examples of deprecating an API version: 3 practical examples, but in reality, you rarely want to copy just one pattern. Most mature API programs blend tactics from several providers.

Here are additional real examples that fill in the gaps.

Twilio: deprecating features inside a long-lived version

Twilio has historically favored long-lived v2010-style API versions, especially for core products like Programmable SMS. Instead of constantly bumping versions, they often:

• Deprecate individual parameters or behaviors.
• Introduce new capabilities in a backward-compatible way.
• Use feature flags or account-level configuration to control access.

A concrete example of deprecating an API version behavior:

• Twilio updates how message delivery status callbacks work.
• Older behavior is marked as deprecated.
• Documentation flags the old pattern, and new apps are guided to the newer callback format.

The underlying version label (2010-04-01, for instance) may stay the same for years, but the contract inside that version evolves. This is a useful strategy if you:

• Can’t easily force customers to upgrade SDKs.
• Need a very stable URL and version identifier for regulatory or contractual reasons.

Slack: pushing real-time clients off legacy APIs

Slack’s platform evolution gives another example of deprecating an API version in a live ecosystem of bots and integrations.

When Slack migrated from the classic Real Time Messaging (RTM) API to newer Events and Web APIs, they:

• Announced deprecation dates for older real-time endpoints.
• Provided migration guides with code samples for popular languages.
• Updated official SDKs to favor the new APIs and warn about deprecated patterns.

This is a strong example of deprecating an API version where the real risk is silent breakage in long-running bots. Slack had to:

• Broadcast deprecation notices in the app and via email.
• Give developers time to rewrite connection logic.
• Provide detailed logging and error messages when deprecated endpoints were called.

AWS: multi-year support and “no surprise” removals

AWS might be the most conservative of all. Many AWS services effectively never remove older API versions, but when they do, the deprecation cycle is long and noisy.

You’ll often see:

• Deprecation notices in the AWS Console.
• Email campaigns targeted to specific accounts that still use the old API.
• Detailed migration runbooks and CloudFormation update paths.

For example, when older cryptographic protocols or outdated instance metadata behaviors are retired, AWS treats them as security and reliability issues. That means long lead times, warnings in logs, and clear migration flags.

If you’re operating infrastructure that can’t afford surprise downtime, AWS provides one of the best examples of slow, predictable deprecation.

Patterns you can reuse from these examples of deprecating an API version

Looking across these examples of deprecating an API version: 3 practical examples (plus the supporting cases), some repeatable patterns emerge.

1. Choose your deprecation style upfront

Most teams gravitate toward one of these:

• Per-tenant versioning (Stripe-style): safer for breaking changes, but more operational complexity.
• Header or media type versioning (GitHub-style): flexible and explicit for clients.
• Global version cutovers (Google-style): simpler operationally, but higher risk and more customer pain.

Your choice shapes every future example of deprecating an API version inside your organization.

2. Communicate in three layers

Every strong example of deprecating an API version uses a multi-channel communication strategy:

• Human-readable: blog posts, changelogs, docs, dashboard banners.
• Machine-readable: headers like Deprecation and Sunset, version metadata, structured error codes.
• Personalized: targeted emails, account manager outreach, or in-product notifications tied to actual usage.

GitHub’s headers, Stripe’s dashboard warnings, and Google Cloud’s release notes all fit this pattern.

3. Give realistic migration windows

In 2024–2025, a 30-day deprecation window is rarely acceptable for anything beyond a minor feature. The better examples of deprecating an API version tend to use:

• 6–12 months for moderate changes.
• 12–24 months for deeply embedded or regulated workflows.

Teams in healthcare and life sciences, for instance, often align deprecation timelines with broader technology and compliance cycles. While not API-specific, resources like the National Institutes of Health and Harvard’s IT guidance can help you frame deprecation in terms of long-term technology sustainability and risk management.

4. Provide migration tooling, not just documentation

The best examples include more than a PDF:

• Diff views: showing old vs. new payloads.
• Automated checks: scripts or dashboards that tell a customer exactly which endpoints and fields they use that are going away.
• Compatibility shims: temporary behavior flags that let clients adopt the new API in stages.

Stripe’s upgrade guides, Google’s migration tools, and AWS’s step-by-step runbooks are all practical examples of deprecating an API version with a safety net.

5. Enforce the deadline—and be ready with exceptions

Every successful example of deprecating an API version has a moment where the old thing actually stops working. When that day comes:

• Return clear, actionable errors, not mysterious 500s.
• Keep a temporary override path for truly stuck customers (for example, a short-term allowlist or emergency extension).
• Monitor metrics and support volume aggressively for at least a week.

Google Cloud and Slack both show how to do this without backpedaling on announced dates.

FAQ: practical questions about deprecating API versions

What are some real examples of deprecating an API version in production?

Real-world examples include Stripe’s date-based versions with per-account upgrades, GitHub’s header-based versioning with Deprecation and Sunset headers, and Google Cloud’s hard end-of-life dates for older APIs. Twilio, Slack, and AWS all provide additional examples of deprecating an API version by retiring specific behaviors, real-time endpoints, or outdated security configurations.

How long should I keep an old API version alive?

There’s no single answer, but looking at the best examples, most providers use 6–24 months for meaningful changes. Shorter windows might work for internal or beta APIs; longer windows make sense for regulated industries, embedded devices, or mission-critical integrations.

What is a good example of communication during API deprecation?

A good example of strong communication is GitHub’s approach: announce deprecation with clear dates, include deprecation headers in responses, update docs, and send targeted emails to affected users. Stripe’s dashboard warnings and upgrade guides are another strong example of deprecating an API version with clear, actionable messaging.

Can I deprecate specific fields without bumping the whole API version?

Yes. Many of the best examples include field-level or behavior-level deprecation. GitHub often retires individual fields or preview features; Twilio and Slack do the same. You can mark fields as deprecated in your schema, log usage, warn in responses, and then remove them after a defined window.

How do I avoid breaking long-lived clients when I deprecate an API version?

Borrow from Stripe and AWS: keep old behavior available for a long time, pin clients to a specific version where possible, and use clear warnings in logs and dashboards. Provide migration guides, sample requests, and—if you can—compatibility flags that let clients adopt new behavior gradually.

If you’re planning your own strategy, treat these examples of deprecating an API version: 3 practical examples (plus the supporting cases) as a menu, not a script. Pick the communication style of GitHub, the gradualism of Stripe, and the clarity of Google’s deadlines, then tune them to your own customers, risk tolerance, and regulatory environment.