Versioning Microservices

title: "Versioning Microservices — Coordinating Versions Across Services" description: "Microservice versioning requires coordinating API versions across dozens of services using API gateways, service meshes, and contract testing to manage dependencies." date: 2026-06-28 lastmod: 2026-06-28 weight: 26 tags: [apis, versioning] }

Microservice versioning manages API versioning across distributed services using API gateways, service mesh routing, consumer-driven contracts, and semantic versioning.

What You'll Learn

• Service-level versioning challenges
• Consumer-driven contracts
• API gateway version routing
• Service mesh traffic splitting

Why It Matters

In a monolith, versioning is per-application. In microservices, each service may have its own version. Coordinating across services prevents dependency hell.

Architecture

flowchart TD
    GW[API Gateway] --> US[User Service v1/v2]
    GW --> OS[Order Service v2]
    GW --> PS[Payment Service v1]
    US --> OS
    US --> PS

Code Examples

# API Gateway version routing
# api_gateway.py
from flask import Flask, request, jsonify
import requests

app = Flask(__name__)

SERVICE_ROUTES = {
    'v1': {
        'users': 'http://user-service-v1:3000',
        'orders': 'http://order-service-v1:3000',
    },
    'v2': {
        'users': 'http://user-service-v2:3000',
        'orders': 'http://order-service-v2:3000',
    }
}

@app.route('/<path:subpath>')
def route_request(subpath):
    version = request.headers.get('Accept-Version', 'v1')
    routes = SERVICE_ROUTES.get(version, SERVICE_ROUTES['v1'])

    service = subpath.split('/')[0]
    if service not in routes:
        return jsonify({"error": "Service not found"}), 404

    target = f"{routes[service]}/{subpath}"
    resp = requests.request(
        method=request.method,
        url=target,
        headers={k: v for k, v in request.headers if k != 'Host'},
        data=request.get_data()
    )
    return (resp.content, resp.status_code, resp.headers.items())

# Kubernetes ingress with version routing
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-gateway
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$2
spec:
  rules:
  - host: api.example.com
    http:
      paths:
      - path: /v1(/|$)(.*)
        backend:
          service:
            name: user-service-v1
            port: 3000
      - path: /v2(/|$)(.*)
        backend:
          service:
            name: user-service-v2
            port: 3000

// Consumer-driven contract testing
// consumer-test.js
const pact = require('@pact-foundation/pact-node');

// User service consumer contract
const consumerContract = {
  consumer: 'OrderService',
  provider: 'UserService',
  interactions: [{
    description: 'get user by id',
    request: { method: 'GET', path: '/users/1' },
    response: {
      status: 200,
      body: { id: 1, name: 'Alice', email: 'alice@example.com' }
    }
  }]
};

// Run contract verification
pact.verifyPacts({
  pactUrls: ['./contracts/user-service.json'],
  providerBaseUrl: 'http://user-service:3000'
});

Common Mistakes

1. No Service Version Registry

Unknown service versions cause dependency conflicts.

2. Mixed Versions in Request Chain

User service v1 calls order service v2 — inconsistent data formatting.

3. No Contract Testing

Relying on documentation alone; contracts catch actual breakage.

4. Synchronous Version Coordination

Services should not require simultaneous deployment across versions.

5. No Backward Compatibility in Internal APIs

Internal services must maintain compatibility just like external ones.

Practice Questions

1. What problem does an API gateway solve for microservice versioning?
2. What is a consumer-driven contract?
3. How does service mesh help with versioning?
4. Why avoid mixed version chains?
5. What is a version registry?

Answers:

1. Routes requests to the correct service version based on URI or headers.
2. A contract created by consumers specifying their API expectations.
3. With traffic splitting (canary, blue-green) for gradual version rollouts.
4. Different versions may return incompatible data formats.
5. A central repository tracking which versions of each service are deployed.

Challenge: Set up an API gateway with version routing. Implement consumer-driven contract tests between two services.

FAQ