APIShift
Back to Blog
Best Practices

API Versioning and Deprecation: A Practical Guide

December 30, 20259 min read

APIs evolve. Features change. Requirements shift. But your consumers expect stability. Here's how to balance innovation with compatibility through smart versioning and graceful deprecation.

Why API Versioning Matters

Without proper versioning, you face an impossible choice:

Option 1: Never Change

Keep the API frozen forever. Technical debt accumulates. Can't fix design mistakes. Can't add new features. Product stagnates.

Option 2: Break Everything

Make changes freely. Consumers break constantly. Trust erodes. Developers avoid your API. Integration costs skyrocket.

The Solution: Strategic Versioning

Versioning lets you evolve your API while maintaining stability for existing consumers. It's the only sustainable path forward.

  • ✓ Consumers choose when to migrate
  • ✓ You can innovate without breaking integrations
  • ✓ Both old and new versions coexist temporarily
  • ✓ Migration happens gradually, not all at once

Versioning Strategies Compared

1. URL Path Versioning (Recommended)

https://api.example.com/v1/users
https://api.example.com/v2/users

✓ Pros

  • • Extremely visible and explicit
  • • Easy to route in load balancers
  • • Simple to test and debug
  • • Works with all HTTP clients
  • • Can cache by version

✗ Cons

  • • URL changes break bookmarks
  • • Multiple codebases to maintain
  • • Can't version individual endpoints

Best for:

Public APIs, REST APIs, when you have significant breaking changes affecting most endpoints

2. Header Versioning

GET /users
Accept: application/vnd.api.v2+json
# or
API-Version: 2

✓ Pros

  • • Clean, stable URLs
  • • RESTful and follows HTTP standards
  • • More flexible content negotiation

✗ Cons

  • • Less visible - easy to miss
  • • Harder to test in browsers
  • • Some tools don't support custom headers
  • • Caching becomes complex

Best for:

Internal APIs, when you want stable URLs, GraphQL APIs

3. Query Parameter Versioning

https://api.example.com/users?version=2
# or
https://api.example.com/users?api_version=2.0

✓ Pros

  • • Easy to add to existing APIs
  • • Visible in logs
  • • Works with all clients

✗ Cons

  • • Mixes versioning with query params
  • • Can be accidentally omitted
  • • Not RESTful
  • • Complicates routing logic

Best for:

Quick fixes, testing, temporary versioning during migration

Semantic Versioning for APIs

Follow semantic versioning (semver) principles adapted for APIs:

MAJORv1 → v2

Breaking changes that require consumer updates:

  • • Removing fields or endpoints
  • • Changing field types or formats
  • • Modifying authentication methods
  • • Restructuring response schemas
  • • Making optional fields required
MINORv1.0 → v1.1

Backward-compatible new features:

  • • Adding new optional fields
  • • Adding new endpoints
  • • Adding new query parameters
  • • Making required fields optional
PATCHv1.1.0 → v1.1.1

Backward-compatible bug fixes:

  • • Fixing incorrect data
  • • Performance improvements
  • • Security patches
  • • Documentation corrections

The API Deprecation Process

Deprecation is the art of sunsetting old API versions without angering your users. Follow this timeline:

Phase 1: Announcement (T-90 days)

📧 Multi-Channel Communication

  • • Email all registered API consumers
  • • Post on developer blog/changelog
  • • Update API documentation
  • • Social media announcements
  • • In-dashboard notifications

Include in announcement:

  • • Exact sunset date
  • • Reason for deprecation
  • • Migration guide with code examples
  • • Support contact information
  • • Timeline for each phase
# Example deprecation notice
POST /api/v1/users
Response Headers:
  Deprecation: true
  Sunset: Sat, 31 Mar 2026 23:59:59 GMT
  Link: <https://api.example.com/v2/users>; rel="successor-version"
  Warning: "299 - API v1 will be sunset on March 31, 2026.
           Migrate to v2: https://docs.example.com/migration"

Phase 2: Soft Deprecation (T-60 days)

  • • Add deprecation warnings to API responses
  • • Send reminder emails to active users
  • • Provide migration assistance/office hours
  • • Track which consumers haven't migrated
  • • Reach out personally to high-value clients
# Monitor migration progress
v1_usage: 10,000 requests/day (60% of traffic)
v2_usage: 6,500 requests/day (40% of traffic)

Phase 3: Hard Deprecation (T-30 days)

  • • Final warning emails
  • • Consider rate limiting old version (gradual throttling)
  • • Offer paid support for stragglers
  • • Prepare customer support for complaints
  • • Test shutdown in staging environment

Phase 4: Sunset (T-0)

  • • Return 410 Gone status code
  • • Provide helpful error message with migration link
  • • Monitor support tickets closely
  • • Have rollback plan ready (just in case)
# Response after sunset
HTTP/1.1 410 Gone
Content-Type: application/json

{
  "error": "api_version_sunset",
  "message": "API v1 was sunset on March 31, 2026",
  "migration_guide": "https://docs.example.com/v1-to-v2",
  "current_version": "https://api.example.com/v2/users",
  "support": "api-support@example.com"
}

Deprecation Best Practices

  • Minimum 90 days notice - Enterprises need time for approval, development, testing, and deployment
  • Provide migration tools - Code generators, diff tools, automated migration scripts
  • Support parallel running - Both versions should work simultaneously during migration period
  • Track usage metrics - Know who's still using deprecated versions so you can reach out
  • Offer paid extended support - For clients who genuinely can't migrate in time
  • Document everything - What changed, why, how to migrate, exact timeline

Real-World Example: Stripe's Approach

Stripe is known for excellent API versioning. Here's what they do right:

1. Dated Versions

Versions are dated (e.g., 2023-10-16) not numbered. This makes it clear when changes were made.

2. Account-Level Versioning

Each account has a default version. You can override per-request with headers. No forced upgrades.

3. Extensive Migration Guides

Every version change has detailed changelog with code examples showing before/after.

4. Long Deprecation Windows

Stripe supports old versions for years, giving developers ample time to migrate.

5. Automatic Upgrades (Optional)

They offer automated migration for simple changes, but it's opt-in only.

Key Takeaways

1

URL path versioning is the safest choice for most public REST APIs due to its visibility and simplicity

2

Version only on breaking changes - Not every change requires a new version number

3

Communicate deprecations early and often - 90 days minimum, multiple channels, clear migration guides

4

Support parallel versions - Both old and new should work simultaneously during migration

5

Track usage and reach out proactively - Don't let stragglers get surprised

Conclusion

API versioning and deprecation are not technical problems—they're communication problems. The best versioning strategy is one that respects your consumers' time and trust.

Version strategically. Deprecate gracefully. Communicate clearly. Your developers will thank you.

And remember: the goal isn't to avoid breaking changes forever—it's to make them painless when they inevitably happen.

Track API Version Changes Automatically

Monitor all your API versions in one place. Get alerts when schemas change. Track deprecation usage.

Start Monitoring FreeSee How It Works

Written by

APIShift Team

Related Articles

API Change Management for Microservices

Best practices for managing APIs in distributed systems

5 Cases Where API Changes Broke Production

Learn from real-world versioning disasters