How do I route API requests by path or header?

Routing API requests by path or header is usually done at an API gateway, reverse proxy, load balancer, or service mesh.

1) Route by path

You match the URL path and send it to a backend.

Example

• /users/* → User service
• /orders/* → Order service

NGINX example

location /users/ {
  proxy_pass http://user-service;
}

location /orders/ {
  proxy_pass http://order-service;
}

Kong example

curl -i -X POST http://localhost:8001/services \
  --data name=user-service \
  --data url=http://user-service:8080

curl -i -X POST http://localhost:8001/services/user-service/routes \
  --data 'paths[]=/users'

2) Route by header

You inspect a request header and route based on its value.

Example

• X-Tenant: premium → Premium backend
• X-Version: v2 → v2 backend

NGINX example

map $http_x_version $backend {
  default http://api-v1;
  v2      http://api-v2;
}

server {
  location / {
    proxy_pass $backend;
  }
}

Kong example

curl -i -X POST http://localhost:8001/routes \
  --data 'paths[]=/api' \
  --data 'headers[x-version][]=v2' \
  --data service.name=api-v2

3) Common patterns

• Path-based routing: best for versioning and resource grouping.
• Header-based routing: best for A/B testing, canary releases, tenant routing, or versioning without changing URLs.

4) Things to watch out for

• Route specificity/order matters.
• Normalize headers and paths consistently.
• Prefer explicit fallbacks/default routes.
• Log matched route for debugging.
• Ensure caching doesn’t ignore routing headers.

If you tell me what platform you’re using (NGINX, Kong, AWS API Gateway, Traefik, Envoy, Kubernetes ingress, etc.), I can give you the exact config.