Introduction to API Versioning

In this tutorial, you'll learn about API Versioning Introduction. We cover key concepts, practical examples, and best practices to help you understand and apply this topic effectively.

API Versioning is the practice of managing changes to your API over time without breaking existing clients, allowing different versions to coexist.

What You'll Learn

By the end of this lesson, you will understand what API Versioning is, why it is needed, and the main strategies available for versioning your API.

Why It Matters

Without versioning, every API change risks breaking mobile apps, third-party integrations, and internal services that depend on the existing contract.

Real-World Use

Stripe's API uses URL versioning (/v1/charges) with a deprecation timeline of 2+ years. Clients opt into new versions explicitly.

Versioning Overview

graph LR
    A[Request] --> B{Version Strategy}
    B --> C["/v1/users"]
    B --> D["Accept: vnd.api.v2+json"]
    B --> E["?version=2"]
    C --> F[V1 Handler]
    D --> G[V2 Handler]
    E --> F

What Problem Does Versioning Solve?

Think of an API like a contract between you and your clients. Once clients start using your API, they depend on its behavior. If you change the response format, remove a field, or modify an endpoint, existing clients break.

Versioning gives you a mechanism to make changes while keeping old behavior available for clients that are not ready to upgrade.

# version_problem.py
# Illustrating the problem of unversioned API changes

def get_user_v1(user_id):
    """Original version returns user with name and email."""
    return {"id": user_id, "name": "Alice", "email": "alice@example.com"}

def get_user_v2(user_id):
    """New version returns nested user object and more fields."""
    return {
        "data": {
            "id": user_id,
            "display_name": "Alice",
            "contact": "alice@example.com",
            "role": "admin",
        },
        "meta": {"version": "2.0"}
    }

# Client expects flat structure (v1 format)
client_expects = {"id": 1, "name": "Alice", "email": "alice@example.com"}

# New format breaks the client
new_response = get_user_v2(1)
print(f"Client expected keys: {set(client_expects.keys())}")
print(f"New response keys: {set(new_response.keys())}")

# The client cannot find 'name' or 'email' in the new format
# This is why versioning exists
print(f"\nClient would break because:")
print(f"  'name' in response: {'name' in new_response}")
print(f"  'data.display_name' available: {'data' in new_response}")

Expected output:

Client expected keys: {'name', 'email', 'id'}
New response keys: {'meta', 'data'}

Client would break because:
  'name' in response: False
  'data.display_name' available: True

Common Mistakes

1. Not Versioning from Day One

Adding versioning later requires migrating all existing clients. Start with /v1/ even if you only have one version.

2. Changing Behavior Without a Version Bump

Any behavior change that could break clients requires a new version. Bug fixes that match documented behavior are exceptions.

3. Supporting Too Many Versions

Each version adds maintenance cost. Limit to 2-3 active versions with clear sunset dates.

4. Inconsistent Version Strategy

Use one strategy consistently. Mixing URL and header versioning confuses clients and complicates implementation.

5. No Deprecation Communication

Clients need advance notice before a version is removed. Communicate deprecation timelines clearly.

Practice Questions

1. What is API versioning?

The practice of managing API changes over time by maintaining multiple versions simultaneously so existing clients are not broken.

2. Why should you version from day one?

Adding versioning retroactively requires migrating all existing clients, which is much harder than planning for it upfront.

3. How many versions should you support?

2-3 active versions maximum. Each additional version increases testing burden and maintenance cost.

4. What happens if you never version your API?

Every change risks breaking clients. Teams become afraid to make improvements, and Technical Debt accumulates.

Challenge

List five scenarios that require a new API version and five that can be done within the same version without breaking clients.

FAQ

Mini Project: Version Impact Analyzer

# version_impact.py
from typing import Dict, List

class VersionImpactAnalyzer:
    def analyze_change(self, old_schema: Dict, new_schema: Dict) -> List[str]:
        breaking = []
        for key in old_schema:
            if key not in new_schema:
                breaking.append(f"Field '{key}' removed")
            elif old_schema[key] != new_schema[key]:
                breaking.append(f"Field '{key}' type changed: {old_schema[key]} -> {new_schema[key]}")
        return breaking

analyzer = VersionImpactAnalyzer()
old = {"id": "int", "name": "str", "email": "str", "age": "int"}
new = {"id": "int", "display_name": "str", "email": "str", "age": "float", "role": "str"}

changes = analyzer.analyze_change(old, new)
print("Breaking changes detected:")
for c in changes:
    print(f"  - {c}")

Expected output:

Breaking changes detected:
  - Field 'name' removed
  - Field 'age' type changed: int -> float

What's Next

You understand the basics. Next, learn why you should version your API, then explore URI path versioning.