API versioning for services in Microservices - System Design Guide

Problem Statement

When a service evolves, changing its API without versioning breaks existing clients. This causes failures and forces all clients to upgrade simultaneously, leading to downtime and poor user experience.

Solution

API versioning allows multiple versions of an API to coexist. Clients specify which version they use, so new changes do not break old clients. This enables gradual upgrades and backward compatibility.

Architecture

Client v1

→API Gateway

↓

Client v2

→API Gateway

This diagram shows clients calling different API versions routed by an API Gateway to corresponding service versions.

Trade-offs

✓ Pros

→

Enables backward compatibility for existing clients while evolving APIs.

→

Allows gradual client migration to newer API versions.

→

Reduces risk of breaking changes causing system-wide failures.

→

Supports parallel development and deployment of multiple API versions.

✗ Cons

→

Increases maintenance overhead for supporting multiple API versions.

→

Requires careful documentation and communication to clients.

→

Can lead to code duplication or complexity in service implementations.

When your service API changes frequently and you have multiple clients that cannot upgrade simultaneously, typically at scale of hundreds or more clients.

When your API is stable with rare changes or you control all clients and can coordinate simultaneous upgrades.

Real World Examples

Amazon

Uses API versioning to allow different versions of its product advertising API to coexist, enabling third-party developers to migrate at their own pace.

Twitter

Maintains multiple API versions to support legacy apps while rolling out new features in newer API versions.

Stripe

Implements API versioning to ensure payment integrations remain stable even as new API features are introduced.

Code Example

The before code breaks clients when the response format changes. The after code uses URL path versioning to keep old and new APIs separate, allowing clients to choose which version to call.

Microservices

### Before (No versioning, breaking change)
from flask import Flask, request, jsonify
app = Flask(__name__)

@app.route('/user')
def get_user():
    # Returns user name as string
    return 'Alice'

### After (With versioning via URL path)
from flask import Flask, request, jsonify
app = Flask(__name__)

@app.route('/v1/user')
def get_user_v1():
    # Old API returns name string
    return 'Alice'

@app.route('/v2/user')
def get_user_v2():
    # New API returns JSON object
    return jsonify({'name': 'Alice', 'id': 123})

Alternatives

Backward Compatibility Only

Instead of versioning, the API is designed to never break old clients by only adding non-breaking changes.

Use when: When API changes are minimal and can be guaranteed backward compatible without versioning.

Feature Flags

Use feature flags to toggle new API behaviors instead of separate versions.

Use when: When changes are small and can be controlled internally without exposing multiple API versions.

Summary

API versioning prevents breaking existing clients when APIs evolve.

It enables multiple API versions to coexist and clients to migrate gradually.

Versioning requires trade-offs in maintenance but improves system stability and client experience.