How do I route API traffic by tenant, version, or region?

A common way to route API traffic by tenant, version, or region is to put an API gateway or edge router in front of your services and make routing decisions based on request metadata.

1) Route by tenant

Use one of these identifiers:

• Host/subdomain: tenantA.api.example.com
• Path prefix: /tenants/tenantA/...
• Header: X-Tenant-Id: tenantA
• JWT claim: tenant_id in the access token

Example

• Request: GET /orders
• Header: X-Tenant-Id: acme
• Gateway routes to:
  • orders-acme-service, or
  • a shared service with tenant-aware data partitioning

When to use

• Subdomain routing is best when tenants need a distinct namespace.
• Header/JWT routing is best when you want a clean public URL and tenant is authenticated.

---

2) Route by version

Versioning is usually done with:

• URL path: /v1/orders, /v2/orders
• Header: Accept: application/vnd.company.v2+json
• Custom header: X-API-Version: 2

Example

• /v1/* → legacy service
• /v2/* → new service

When to use

• Path versioning is simplest and most common.
• Header versioning is cleaner for clients but harder to debug and cache.

---

3) Route by region

Use:

• Geo-DNS / latency-based DNS
• Edge POP / CDN / global load balancer
• Region header: X-Region: eu-west-1
• Client location inferred at the edge

Example

• Users in Europe route to eu-api.example.com
• Users in US route to us-api.example.com

When to use

• Prefer geo/latency routing for user experience and compliance.
• Use explicit region overrides for admin or failover cases.

---

Common routing patterns

A. Combine dimensions

You can combine tenant + version + region:

• Host: acme.eu.api.example.com
• Path: /v2/orders
• Gateway decides:
  • tenant = acme
  • region = eu
  • version = v2

This is useful, but keep the scheme simple so it doesn’t become hard to operate.

B. Route at multiple layers

• DNS / edge: region
• Gateway: version and tenant
• Service mesh: canary, retries, traffic splitting

---

Example rule set

1. If path starts with /v2/, send to v2 backend
2. If header X-Tenant-Id=acme, add tenant context or route to tenant-specific pool
3. If request comes from EU, send to eu-cluster
4. Otherwise send to default cluster

---

Best practices

• Keep versioning explicit and stable.
• Avoid too many routing keys in the URL if you can use headers/claims.
• Use consistent tenant identification across all layers.
• Put authorization before routing if tenant access must be verified.
• Add fallbacks for regional failover.
• Log the routing decision for observability.

---

Example in practice

If you use an API gateway like Kong, NGINX, Apigee, AWS API Gateway, or Envoy, you can configure:

• path-based routes for API versioning
• header-based matching for tenant
• geo-based upstream selection for region

---

If you want, I can show you:

1. a Kong/NGINX/Envoy example, or
2. a reference architecture for tenant/version/region routing.