api traffic routing by header and version

Routing API traffic by header and version is a common way to do API versioning and canary/blue-green traffic splitting.

Common patterns

1) Route by custom header

You send a request header like:

• X-API-Version: v1
• X-API-Version: v2
• X-Canary: true

Then your gateway / ingress / load balancer routes based on that header.

Example

GET /users
X-API-Version: v2

Routes to the v2 backend.

---

2) Route by version in the path

This is the most common versioning style:

• /v1/users
• /v2/users

This is not header-based, but it’s often compared with header versioning.

---

3) Route by Accept header

Content negotiation style:

Accept: application/vnd.myapi.v2+json

Useful when you want to keep URLs stable and encode version in media type.

---

When to use header-based routing

Use header routing if you want:

• same URL for multiple versions
• easier internal canary testing
• explicit version selection from clients
• gradual rollout to selected users

---

Example routing rules

NGINX

map $http_x_api_version $backend {
    default backend_v1;
    v2      backend_v2;
}

server {
    location / {
        proxy_pass http://$backend;
    }
}

---

Kubernetes Ingress / Gateway

If your ingress controller supports header matching, you can define rules such as:

• if X-API-Version = v2 → send to service-v2
• else → service-v1

---

API Gateway examples

Most gateways support this:

• Kong: route based on headers
• AWS API Gateway: route using stages, mapping, or Lambda-based logic
• Apigee: header-based conditional flows
• Traefik / Envoy / Istio: header match and weighted routing

---

Best practices

• Keep a default version for clients that don’t send a header.
• Use semantic versioning carefully; often route only major versions.
• Add fallback behavior so missing/invalid headers don’t break traffic.
• Log the selected version for observability.
• Document the header clearly for clients.

---

Example strategy

A typical setup:

• no header → route to v1
• X-API-Version: v2 → route to v2
• X-Canary: true → route to canary backend for testing

---

If you want, I can give you:

1. a Kubernetes/Istio example,
2. an NGINX config, or
3. a Spring Boot / API Gateway implementation.