Why Version Your API — Complete Guide

# why_version.py
from typing import Any, Dict, List, Optional
import json

class VersionUseCase:
    def __init__(self, name: str, description: str, severity: str):
        self.name = name
        self.description = description
        self.severity = severity

use_cases = [
    VersionUseCase(
        "Mobile App Compatibility",
        "Users on old app versions cannot update immediately. The API must support both.",
        "Critical"
    ),
    VersionUseCase(
        "Third-Party Integrations",
        "Partners build against your API. Breaking changes break their integration.",
        "Critical"
    ),
    VersionUseCase(
        "Gradual Migration",
        "Teams migrate service by service, not all at once.",
        "High"
    ),
    VersionUseCase(
        "A/B Testing",
        "Test new response formats with a subset of clients before full rollout.",
        "Medium"
    ),
    VersionUseCase(
        "Regulatory Compliance",
        "Different versions may need different data handling for compliance.",
        "High"
    ),
]

print("Why You Need API Versioning:")
print("=" * 50)
for uc in use_cases:
    print(f"\n[{uc.severity}] {uc.name}")
    print(f"  {uc.description}")

# backward_compat.py
class BackwardCompatibilityDemo:
    def __init__(self):
        self.versions = {"v1": self._handle_v1, "v2": self._handle_v2}

    def handle(self, version: str, data: dict) -> dict:
        handler = self.versions.get(version)
        if not handler:
            return {"error": f"Unknown version {version}"}
        return handler(data)

    def _handle_v1(self, data: dict) -> dict:
        return {
            "id": data.get("id"),
            "name": data.get("name"),
            "email": data.get("email"),
        }

    def _handle_v2(self, data: dict) -> dict:
        return {
            "data": {
                "id": data.get("id"),
                "display_name": data.get("name"),
                "contact": data.get("email"),
                "role": data.get("role", "user"),
            },
            "meta": {"version": "v2"},
        }

api = BackwardCompatibilityDemo()
sample = {"id": 1, "name": "Alice", "email": "alice@example.com", "role": "admin"}

print("Same data, two versions:")
print(f"V1: {api.handle('v1', sample)}")
print(f"V2: {api.handle('v2', sample)}")

# version_decision.py
from typing import Dict, List

class VersionDecision:
    def __init__(self):
        self.factors: Dict[str, int] = {}

    def add_factor(self, factor: str, weight: int = 1):
        self.factors[factor] = weight

    def evaluate(self, has_external_clients: bool,
                 mobile_app: bool, team_size: int,
                 expected_lifetime: str) -> Dict:
        score = 0
        reasons = []

        if has_external_clients:
            score += 3
            reasons.append("External clients require stability")

        if mobile_app:
            score += 3
            reasons.append("Mobile apps update slowly")

        if team_size > 5:
            score += 1
            reasons.append("Larger teams benefit from explicit contracts")

        if expected_lifetime == "long":
            score += 2
            reasons.append("Long-lived APIs need evolution path")
        elif expected_lifetime == "short":
            score -= 1
            reasons.append("Short-lived projects may skip versioning")

        return {
            "score": score,
            "recommendation": "Version from day one" if score >= 4 else "Consider simple approach",
            "reasons": reasons,
        }

decider = VersionDecision()
result = decider.evaluate(
    has_external_clients=True,
    mobile_app=True,
    team_size=10,
    expected_lifetime="long"
)
print(f"Score: {result['score']}")
print(f"Recommendation: {result['recommendation']}")
for r in result['reasons']:
    print(f"  - {r}")