Skip to content

Versioning Best Practices

DodaTech 2 min read

title: "Versioning Best Practices — Guidelines for API Version Management" description: "API versioning best practices include starting early, supporting 2-3 versions max, using deprecation headers, documenting migrations, and testing compatibility." date: 2026-06-28 lastmod: 2026-06-28 weight: 30 tags: [apis, versioning] }

API versioning best practices cover starting to version early, limiting supported versions to 2-3, clear deprecation policies, and automated compatibility testing.

What You'll Learn

  • Versioning rules and conventions
  • Deprecation and sunset policies
  • Team workflows for version management

Why It Matters

Following versioning best practices prevents common mistakes, reduces client friction, and makes API evolution sustainable over years.

Best Practices Summary

flowchart TD
    BP[Best Practices] --> V[Version from Day 1]
    BP --> L[Limit to 2-3 Versions]
    BP --> D[Deprecation Policy]
    BP --> M[Migration Guides]
    BP --> T[Automated Testing]
    BP --> C[Communication]

Code Examples

# Best practice: version configuration
from dataclasses import dataclass

@dataclass
class VersionPolicy:
    """Centralized version management."""
    latest: str = '2'
    supported: list = None
    deprecated: list = None
    sunset_days: int = 180  # 6 months notice

    def __post_init__(self):
        self.supported = self.supported or ['2', '3']
        self.deprecated = self.deprecated or ['1']

    def is_supported(self, version):
        return version in (self.supported or [])

    def is_deprecated(self, version):
        return version in (self.deprecated or [])

    def sunset_date(self, version):
        """Calculate sunset date for a deprecated version."""
        from datetime import datetime, timedelta
        return (datetime.utcnow() + timedelta(days=self.sunset_days)).isoformat()

# Best practice: consistent version header
@app.after_request
def apply_version_policy(response):
    version = getattr(request, 'api_version', '1')
    policy = VersionPolicy()

    if policy.is_deprecated(version):
        response.headers['Deprecation'] = 'true'
        response.headers['Sunset'] = policy.sunset_date(version)
        response.headers['Link'] = f'</v{policy.latest}>; rel="successor-version"'

    response.headers['X-API-Version'] = version
    return response

# Best practice: version routing table
VERSION_ROUTING = {
    '1': {'base_path': '/v1', 'module': 'api.v1'},
    '2': {'base_path': '/v2', 'module': 'api.v2'},
    '3': {'base_path': '/v3', 'module': 'api.v3'},
}

// Best practice: version validation middleware
const SUPPORTED_VERSIONS = ['2', '3'];
const DEPRECATED_VERSIONS = ['1'];
const SUNSET_DAYS = 180;

function versionMiddleware(req, res, next) {
  const version = req.headers['accept-version'] || '2';

  if (!SUPPORTED_VERSIONS.includes(version)) {
    return res.status(400).json({
      error: 'Unsupported version',
      supported: SUPPORTED_VERSIONS,
      latest: '3'
    });
  }

  if (DEPRECATED_VERSIONS.includes(version)) {
    const sunset = new Date(Date.now() + SUNSET_DAYS * 86400000).toUTCString();
    res.set({
      'Deprecation': 'true',
      'Sunset': sunset,
      'Link': '</api/v3>; rel="successor-version"'
    });
  }

  req.apiVersion = version;
  next();
}

Common Mistakes

1. No Versioning Until It's Too Late

Adding versioning after clients depend on the API is painful.

2. Supporting Too Many Versions

Each version adds maintenance burden. Limit to 2-3.

3. No Deprecation Policy

Clients don't know when a version will be removed.

4. Inconsistent Version Application

Some endpoints versioned, others not.

5. No Automated Compatibility Tests

Breaking changes slip through without automated checks.

Practice Questions

  1. How many API versions should you support?
  2. What is the minimum deprecation period?
  3. When should you start versioning your API?
  4. What headers should deprecated versions include?
  5. How do you communicate version changes?

Answers:

  1. 2-3 active versions maximum.
  2. 6-12 months deprecation notice before removal.
  3. From day one, even before the first public release.
  4. Deprecation, Sunset, and Link (successor-version) headers.
  5. Deprecation headers, changelog, migration guides, email notifications.

Challenge: Create a version management policy document for your API team. Include version lifecycle, deprecation timeline, and team responsibilities.

FAQ

How do I handle security patches for deprecated versions?

: Backport critical security fixes to all supported versions.

Should I version internal and external APIs differently?

: Internal APIs can use faster deprecation cycles with more frequent versions.

What is the cost of supporting an old version?

: Maintenance overhead, testing burden, and opportunity cost of not evolving.

← Previous Uri Versioning Next → Versioning Graphql

Built by the developers of DodaTech

Doda Browser, DodaZIP & Durga Antivirus Pro

Home Browse Api Versioning