API Versioning & Lifecycle Management

Every successful API eventually needs to change. New features require new fields. Business logic evolves. Security requirements tighten. The challenge is evolving your API without breaking the clients that depend on it. This guide covers the engineering and organizational practices for managing API change safely.

---

Versioning Strategies

Strategy	Example	Pros	Cons
URL path	/v2/orders	Clear, easy to route	URL pollution, hard to deprecate
Query parameter	/orders?version=2	Optional, flexible	Easy to forget, inconsistent
Header	Accept: application/vnd.api.v2+json	Clean URLs, content negotiation	Hidden, tooling challenges
No versioning	Additive changes only	Simple, no version sprawl	Can’t make breaking changes

Recommended: URL Path + Additive Changes

/v1/orders        ← Maintained for 12 months after v2 launch
/v2/orders        ← Current version
/v2/orders/{id}   ← New fields added without version bump

---

Breaking vs Non-Breaking Changes

Change	Breaking?	Action
Add optional field to response	No	Ship it
Add optional query parameter	No	Ship it
Add required request field	Yes	New version
Remove response field	Yes	Deprecate, then new version
Change field type (string → number)	Yes	New version
Change error format	Yes	New version
Rename endpoint	Yes	New version
Add new endpoint	No	Ship it
Change auth mechanism	Yes	New version + migration period

---

Deprecation Policy

api_lifecycle:
  phases:
    active:
      description: "Current recommended version"
      support: "Full support, new features added"
    
    deprecated:
      description: "Still functional, no new features"
      support: "Security fixes only"
      duration: "12 months minimum"
      actions:
        - Sunset header returned on every response
        - Deprecation notice in API docs
        - Email notification to all registered consumers
        - Usage dashboard tracking migration progress
    
    retired:
      description: "No longer available"
      response: "410 Gone with migration guide URL"

  deprecation_headers:
    # RFC 8594
    Deprecation: "Sun, 01 Jan 2026 00:00:00 GMT"
    Sunset: "Mon, 01 Jul 2026 00:00:00 GMT"
    Link: '<https://api.example.com/docs/migration-v2-v3>; rel="successor-version"'

---

Consumer Migration

Phase 1: Announce (6 months before sunset)
├── Publish migration guide
├── Email all API key holders
└── Add deprecation headers to all v1 responses

Phase 2: Monitor (ongoing)
├── Track v1 vs v2 usage daily
├── Contact top 10 v1 consumers directly
└── Offer migration support

Phase 3: Final Warning (30 days before sunset)
├── Rate limit v1 (slower responses)
├── Return warning in response body
└── Direct outreach to remaining consumers

Phase 4: Sunset
├── Return 410 Gone for all v1 requests
├── Response body includes migration guide URL
└── Keep documentation available

---

Anti-Patterns

Anti-Pattern	Problem	Fix
No versioning strategy	Breaking changes surprise consumers	Establish versioning from API v1
Too many versions	Maintenance burden grows linearly	Max 2 active versions, deprecate aggressively
Immediate sunset	Consumers can’t migrate in time	12-month minimum deprecation period
Version per feature	v47 of the API, nobody knows which to use	Version on breaking changes only, not features
No changelog	Consumers don’t know what changed	Automated changelog from OpenAPI diff

---

Checklist

• Versioning strategy documented and consistent
• Breaking vs non-breaking change guidelines published
• Deprecation policy with minimum timeline
• Deprecation headers (Sunset, Deprecation) on deprecated versions
• Consumer tracking: know who uses each version
• Migration guide published before deprecation
• Changelog: automated from OpenAPI spec diff
• Maximum 2 active versions at any time

---

:::note[Source] This guide is derived from operational intelligence at Garnet Grid Consulting. For API design consulting, visit garnetgrid.com. :::