API Versioning Strategies: Complete Guide for REST & GraphQL APIs (2026)

What Is API Versioning?

API versioning is the practice of managing changes to an API by creating distinct versions that allow developers to upgrade at their own pace. Without versioning, every API change would potentially break existing client applications.

Think of it like software versioning (iOS 17 vs iOS 16), but for APIs. Different clients can use different versions simultaneously while you roll out improvements, bug fixes, or breaking changes.

A Simple Example

// v1: Original endpoint
GET /api/v1/users
Response: { "id": 123, "name": "Alice" }

// v2: Breaking change - added email requirement
GET /api/v2/users
Response: { "id": 123, "full_name": "Alice Smith", "email": "alice@example.com" }

// Both versions can coexist!
// Old clients continue using v1 (no breaking changes)
// New clients adopt v2 (better data model)

Why Versioning Matters

1. Prevents Breaking Changes

Without versioning, fixing a bug or adding a field could break thousands of production applications. Versioning lets you introduce changes safely.

2. Enables Gradual Migration

Enterprise clients can't always upgrade instantly. Versioning gives them months (or years) to migrate on their schedule.

3. Supports Multiple Client Types

Mobile apps (slow update cycles), web apps (frequent updates), and server-to-server integrations (conservative upgrades) can all use different versions.

4. Builds Developer Trust

Developers trust APIs that don't break unexpectedly. Good versioning practices signal professionalism and reliability.

The 5 Main Versioning Strategies

There are 5 common ways to version REST APIs, each with trade-offs:

Recommendation: For most APIs, URI path versioning (/v1/, /v2/) is the best choice. It's simple, explicit, and supported by all HTTP tools.

URI Path Versioning (Most Common)

The most popular approach: put the version number in the URL path.

GET https://api.stripe.com/v1/charges
GET https://api.twilio.com/2010-04-01/Accounts
GET https://api.twitter.com/2/tweets

Implementation in Express.js

import express from 'express';

const app = express();

// v1 routes
app.get('/api/v1/users', (req, res) => {
  res.json({
    id: 123,
    name: 'Alice'  // Old format
  });
});

// v2 routes - breaking change!
app.get('/api/v2/users', (req, res) => {
  res.json({
    id: 123,
    full_name: 'Alice Smith',  // Changed field name
    email: 'alice@example.com'  // Added required field
  });
});

// Both versions coexist
app.listen(3000);

Pros

• ✅ Explicit and visible - version is obvious in every request
• ✅ Easy to test - just change the URL in Postman/curl
• ✅ Cacheable - CDNs and proxies can cache by URL
• ✅ Routing-friendly - easy to route to different codebases
• ✅ Documentation-friendly - clear separation in docs

Cons

• ❌ URI pollution - version in every endpoint
• ❌ Not RESTful purist - URLs should represent resources, not versions
• ❌ Migration overhead - clients must update all URLs

When to Use

Use URI path versioning when:

• 🎯 You're building a public API for external developers
• 🎯 Simplicity and discoverability matter
• 🎯 You want version-specific monitoring/logging
• 🎯 You might deploy different versions to different servers

Query Parameter Versioning

Put the version in a query parameter:

GET /api/users?version=1
GET /api/users?version=2
GET /api/users?v=2  // Shorter alias

Implementation

app.get('/api/users', (req, res) => {
  const version = req.query.version || req.query.v || '1';  // Default to v1
  
  if (version === '2') {
    res.json({
      id: 123,
      full_name: 'Alice Smith',
      email: 'alice@example.com'
    });
  } else {
    res.json({
      id: 123,
      name: 'Alice'
    });
  }
});

Pros

• ✅ Clean URIs - base path stays the same
• ✅ Optional parameter - can default to latest or v1
• ✅ Easy to add - no routing changes needed

Cons

• ❌ Cache invalidation issues - some proxies ignore query params
• ❌ Less discoverable - not obvious from the URL structure
• ❌ Can be forgotten - easy to omit in requests

When to Use

Use query parameter versioning when:

• 🎯 You want clean base URLs
• 🎯 You're adding versioning to an existing API
• 🎯 You want to make version optional with a default

Custom Header Versioning

Use a custom HTTP header to specify the version:

GET /api/users
X-API-Version: 2

# Or date-based (GitHub style)
GET /api/users
X-GitHub-Api-Version: 2026-03-01

Implementation

app.get('/api/users', (req, res) => {
  const version = req.headers['x-api-version'] || '1';
  
  if (version === '2') {
    res.json({ id: 123, full_name: 'Alice Smith', email: 'alice@example.com' });
  } else {
    res.json({ id: 123, name: 'Alice' });
  }
});

Real-World Example: GitHub Date-Based Versioning

GitHub uses date-based versioning in headers:

curl https://api.github.com/users/octocat \
  -H "X-GitHub-Api-Version: 2026-03-01"

# This locks the client to the API behavior as of March 1, 2026

Why date-based? GitHub can make small improvements continuously without bumping major versions. Clients pin to a date and get a stable snapshot.

Pros

• ✅ Clean URIs - no version in the path
• ✅ RESTful - URLs represent resources, headers handle metadata
• ✅ Flexible - can use semantic versions, dates, or custom schemes

Cons

• ❌ Hidden - not obvious from URL
• ❌ Harder to test - must set headers in every tool
• ❌ Documentation overhead - requires explicit header instructions
• ❌ Cache complexity - must configure Vary: X-API-Version

When to Use

Use custom header versioning when:

• 🎯 You want truly RESTful URIs
• 🎯 Your clients are sophisticated (servers, not browsers)
• 🎯 You want date-based or custom versioning schemes

Accept Header Versioning (Content Negotiation)

Use the standard Accept header for content negotiation:

GET /api/users
Accept: application/vnd.myapi.v2+json

# Or simpler vendor MIME type
GET /api/users
Accept: application/vnd.myapi+json;version=2

Implementation

app.get('/api/users', (req, res) => {
  const accept = req.headers.accept || '';
  
  if (accept.includes('v2') || accept.includes('version=2')) {
    res.type('application/vnd.myapi.v2+json');
    res.json({ id: 123, full_name: 'Alice Smith', email: 'alice@example.com' });
  } else {
    res.type('application/vnd.myapi.v1+json');
    res.json({ id: 123, name: 'Alice' });
  }
});

Pros

• ✅ HTTP standard - uses content negotiation correctly
• ✅ Clean URIs - no version in path
• ✅ Semantically correct - different versions = different representations

Cons

• ❌ Complex - vendor MIME types are hard to understand
• ❌ Poor tooling - many tools don't support custom MIME types well
• ❌ Browser unfriendly - can't test in browser address bar
• ❌ Debugging difficulty - harder to see what version failed

When to Use

Use Accept header versioning when:

• 🎯 You're a REST purist following HTTP specs strictly
• 🎯 Your API returns different media types (XML, JSON, Protocol Buffers)
• 🎯 You want academic correctness over pragmatism

Subdomain Versioning

Use different subdomains for different versions:

https://api.example.com/users       # v1 (default)
https://v2.api.example.com/users  # v2
https://v3.api.example.com/users  # v3

Real-World Example: Salesforce

Salesforce uses subdomains for different API families:

https://login.salesforce.com        # Authentication
https://na1.salesforce.com/services/data/v56.0  # Data API v56
https://na1.salesforce.com/services/data/v57.0  # Data API v57

Pros

• ✅ Complete isolation - different servers, databases, code
• ✅ Independent scaling - scale v1 and v2 separately
• ✅ Blue-green deployments - easy to roll out v2 gradually
• ✅ Clear separation - no shared routing logic

Cons

• ❌ Infrastructure overhead - separate DNS, SSL certs, load balancers
• ❌ CORS complexity - cross-origin requests between versions
• ❌ Cost - running multiple production environments
• ❌ Maintenance burden - patching vulnerabilities across versions

When to Use

Use subdomain versioning when:

• 🎯 You need complete physical isolation (security, compliance)
• 🎯 Different versions have vastly different infrastructure needs
• 🎯 You're a large enterprise with dedicated DevOps resources
• 🎯 You're doing a major rewrite (v2 is completely new codebase)

Semantic Versioning for APIs

Should you use semantic versioning (MAJOR.MINOR.PATCH) for APIs?

The Semver Format

MAJOR.MINOR.PATCH

MAJOR: Breaking changes (v1 → v2)
MINOR: New features, backward compatible (v1.0 → v1.1)
PATCH: Bug fixes, backward compatible (v1.0.0 → v1.0.1)

Examples:
/api/v1.2.3/users  # Full semver
/api/v1/users      # Major version only (recommended)

Recommendation: Major Version Only

For most APIs, expose only the MAJOR version publicly:

✅ Good: /api/v1/users
✅ Good: /api/v2/users

❌ Avoid: /api/v1.2.3/users  # Too granular
❌ Avoid: /api/v1.2/users    # Clients don't care about MINOR

Why Major Version Only?

• 📌 Simplicity: Clients only care about breaking changes
• 📌 Flexibility: You can add features and fix bugs without client updates
• 📌 Less noise: No version churn (v1.1 → v1.2 → v1.3)
• 📌 Industry standard: Stripe, GitHub, AWS all use major versions only

When to Use Full Semver

Use MAJOR.MINOR versioning when:

• 🎯 You're building SDK libraries (not HTTP APIs)
• 🎯 Clients need fine-grained control over features
• 🎯 You're versioning internal microservices

Breaking vs Non-Breaking Changes

The #1 rule of API versioning: Don't break existing clients.

Breaking Changes (Require Version Bump)

❌ Removing a field
  v1: { "name": "Alice" }
  v2: { "full_name": "Alice" }  // "name" removed!

❌ Renaming a field
  v1: { "user_id": 123 }
  v2: { "id": 123 }  // Renamed!

❌ Changing data types
  v1: { "created_at": 1646611200 }  // Unix timestamp
  v2: { "created_at": "2026-03-09T20:00:00Z" }  // ISO string

❌ Making optional field required
  v1: POST /users { "name": "Alice" }  // email optional
  v2: POST /users { "name": "Alice", "email": "..." }  // email required!

❌ Changing error response format
  v1: { "error": "Not found" }
  v2: { "errors": [{ "code": "NOT_FOUND", "message": "..." }] }

❌ Removing an endpoint
  v1: DELETE /api/users/:id
  v2: (endpoint removed)

❌ Changing status codes
  v1: Returns 404 for missing user
  v2: Returns 410 for missing user

❌ Changing authentication method
  v1: API key in query param
  v2: Bearer token in header

Non-Breaking Changes (Safe Without Version Bump)

✅ Adding new optional fields
  v1: { "name": "Alice" }
  v1: { "name": "Alice", "email": "alice@example.com" }  // Safe!

✅ Adding new endpoints
  v1: GET /users
  v1: GET /users/:id/orders  // New endpoint, safe

✅ Adding new optional query parameters
  v1: GET /users
  v1: GET /users?include_inactive=true  // Optional param, safe

✅ Relaxing validation (making required field optional)
  v1: POST /users requires email
  v1: POST /users email now optional  // Safe (more permissive)

✅ Adding new error codes (keeping existing ones)
  v1: Returns 400, 404, 500
  v1: Returns 400, 404, 422, 500  // Added 422, safe

✅ Adding new values to enums
  v1: status = "active" | "inactive"
  v1: status = "active" | "inactive" | "suspended"  // Safe if clients ignore unknown

✅ Bug fixes that don't change contract
  v1: Returns duplicate items in list
  v1: Returns deduplicated list  // Bug fix, safe

The Robustness Principle (Postel's Law)

When to Version (And When Not To)

When to Create a New Version

• ✅ Breaking changes: Anything that breaks existing clients (see above)
• ✅ Major data model changes: Switching from flat to nested objects
• ✅ Authentication changes: OAuth 1 → OAuth 2, API keys → JWT
• ✅ Response format changes: XML → JSON, single object → paginated list
• ✅ Batch vs non-batch: GET /user/:id → GET /users (array)

When NOT to Version

• ❌ Adding optional fields: Just add them (non-breaking)
• ❌ Bug fixes: Fix in current version, backport to old versions if supported
• ❌ Performance improvements: Transparent to clients
• ❌ Adding new endpoints: New resources don't break existing ones
• ❌ Security patches: Apply to all supported versions immediately

Version Fatigue: Don't Over-Version

❌ Bad: v1, v1.1, v1.2, v2, v2.1, v2.2, v3, v3.1  // Version fatigue!

✅ Good: v1, v2, v3  // Major versions only

The Stripe Rule

Stripe has a great policy: New features are added to the latest version only. Want the new feature? Upgrade. This incentivizes migration.

Deprecation & Sunset Strategies

Eventually, you need to retire old versions. Do it gracefully:

The 4-Phase Deprecation Process

Sunset Response Example

HTTP/1.1 410 Gone
Content-Type: application/json

{
  "error": "API_VERSION_SUNSET",
  "message": "API v1 was sunset on September 1, 2026",
  "migration_guide": "https://docs.example.com/migrate-v1-to-v2",
  "support_email": "api-support@example.com"
}

HTTP Headers for Deprecation

# RFC 8594: The Sunset HTTP Header
Sunset: Sat, 01 Sep 2026 00:00:00 GMT

# Custom deprecation warning
Deprecation: true
X-API-Warn: "v1 will be sunset on 2026-09-01. Migrate to v2: https://..."

# Link to migration guide
Link: <https://docs.example.com/migrate-v1-to-v2>; rel="deprecation"

How Long to Support Old Versions?

GraphQL Versioning (The No-Versioning Approach)

GraphQL takes a different approach: no versioning at all. Instead, it uses schema evolution.

How GraphQL Avoids Versioning

• ✅ Additive changes only: Add new fields, never remove old ones
• ✅ Deprecation markers: Mark fields as @deprecated
• ✅ Client-driven queries: Clients request only the fields they need
• ✅ Gradual migration: Clients update field by field, not all at once

Example: Deprecating a Field

type User {
  id: ID!
  name: String! @deprecated(reason: "Use 'fullName' instead")
  fullName: String!  # New field
  email: String!
}

# Old clients continue using "name"
query {
  user(id: "123") {
    name  # Still works, returns data
  }
}

# New clients use "fullName"
query {
  user(id: "123") {
    fullName  # Better field name
  }
}

When GraphQL Versioning Makes Sense

Even GraphQL sometimes needs versions for:

• 🎯 Breaking type changes: Changing ID! to String!
• 🎯 Authentication overhaul: New auth mechanism
• 🎯 Complete schema redesign: GraphQL v2 with new root types

Solution: GraphQL can use URI path versioning too:

POST https://api.example.com/graphql/v1
POST https://api.example.com/graphql/v2

Real-World Examples

Stripe: Date-Based Versions

Stripe uses date-based versions with pinning:

curl https://api.stripe.com/v1/charges \
  -u sk_test_... \
  -H "Stripe-Version: 2026-03-01"

# Each account pins to a specific date version
# Upgrade by changing the pinned version in dashboard

Why date-based? Stripe makes small improvements continuously. Dates give clients fine-grained control without version number inflation.

GitHub: API Version in Header

GitHub uses custom headers with date versions:

curl https://api.github.com/users/octocat \
  -H "X-GitHub-Api-Version: 2026-03-01"

Twitter: URI Path Versioning

Twitter (now X) uses simple numeric versions in the path:

https://api.twitter.com/1.1/statuses/update.json  # v1.1 (deprecated)
https://api.twitter.com/2/tweets                  # v2 (current)

AWS: Service-Specific Versioning

AWS uses dates in the API action target:

POST / HTTP/1.1
Host: dynamodb.us-east-1.amazonaws.com
X-Amz-Target: DynamoDB_20120810.GetItem

# Date embedded in target header (2012-08-10)

Twilio: Date-Based URI Path

Twilio uses dates in the URI (their first API release date):

https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages

Migration Strategies

How do you get clients to migrate from v1 to v2?

1. Dual Write Pattern

Write to both old and new schemas during transition:

// v1 client writes
POST /api/v1/users
{ "name": "Alice" }

// Server transforms and writes to both schemas
db.usersV1.insert({ name: "Alice" })
db.usersV2.insert({ full_name: "Alice", email: null })  // Transform

// Eventually drop v1 writes when all clients migrated

2. Adapter Pattern

Build adapters that convert between v1 and v2:

// v1 endpoint (adapter)
app.get('/api/v1/users/:id', async (req, res) => {
  const user = await getUserV2(req.params.id);  // Fetch from v2
  res.json(transformV2toV1(user));  // Transform back to v1 format
});

function transformV2toV1(userV2) {
  return {
    id: userV2.id,
    name: userV2.full_name.split(' ')[0]  // Convert back
  };
}

3. Feature Flags for Gradual Rollout

// Enable v2 for beta testers only
app.get('/api/v2/users', (req, res) => {
  const user = await getUser(req.userId);
  
  if (featureFlags.isEnabled('v2-api', user)) {
    return res.json(formatV2(user));  // v2 format
  } else {
    return res.json(formatV1(user));  // v1 format (fallback)
  }
});

4. SDKs with Auto-Migration

Provide official SDKs that handle version differences:

// SDK handles version internally
const client = new ApiClient({ version: '2' });

// Client code stays the same
const user = await client.users.get('123');

// SDK automatically uses /api/v2/users under the hood

5. Incentivize Migration

• 🎁 New features only in v2: Want webhooks? Upgrade to v2
• 🎁 Better performance in v2: v1 gets 100 req/min, v2 gets 1000 req/min
• 🎁 Credits/discounts: Migrate by Q2 2026, get 3 months free
• 🎁 Priority support: v2 users get faster support responses

Best Practices

Sunset: Sat, 01 Sep 2026 00:00:00 GMT
Deprecation: true

Common Mistakes to Avoid

API Versioning Checklist