Gateway Routing

Gateway Routing exposes a single endpoint to clients and directs each incoming request to the appropriate backend service based on attributes of the request. Clients address one stable URL; the gateway decides where the request actually goes. This decouples clients from the backend topology so services can be added, moved, split, or versioned without changing consumers.

How It Works

The gateway maintains routing rules that map request attributes (path prefix, host header, HTTP method, headers, or query parameters) to upstream services. When a request arrives, the gateway matches it against the rules and forwards it to the selected service, often consulting service discovery for the current instance address. Rules can be changed at runtime to reroute traffic.

Because routing is centralized and dynamic, the gateway can support versioned endpoints, gradual rollouts (canary), and instant cutovers (blue-green) by adjusting where matching requests are sent.

Routing rules are evaluated in priority order, so more specific rules can override general ones, and they can rewrite paths, strip prefixes, or inject headers before forwarding. Because rules are data rather than code, they can be stored in a config store and changed at runtime, which is what makes traffic shifting for canary releases and instant blue-green cutovers possible without redeploying the gateway.

When to Use It

Use gateway routing whenever you want a single public entry point in front of many services, need to hide or evolve backend structure, must support multiple API versions cleanly, or want to shift traffic for canary and blue-green deployments without client changes.

A system with one backend or a simple load balancer may not need explicit routing rules.

It is also useful for consolidating several legacy systems behind one modern API surface, presenting a coherent set of paths while quietly routing to disparate backends.

Trade-offs

Routing centralizes control and decouples clients from topology, but the gateway becomes a critical component on the request path that must be highly available and fast. Complex rule sets can be hard to reason about and test. Misconfigured rules can misroute or expose services. The benefit is flexibility: backend changes stay invisible to clients. Treating routes as versioned configuration, reviewed and tested like code, prevents the rule set from becoming an opaque tangle and makes traffic-shifting changes auditable and reversible.

Related Patterns

Gateway Routing is one of the three gateway responsibilities with Gateway Aggregation and Gateway Offloading, together forming the API Gateway pattern. It typically relies on Service Discovery to find current instances and enables canary and blue-green deployment strategies. The Aggregator and Backend for Frontend patterns frequently sit alongside it within the same gateway.

Example

A gateway routes /v1/orders/* to the orders-v1 service and /v2/orders/* to a rewritten orders-v2 service. To launch v2 safely, the team first adds a rule sending 5% of /v2 traffic to a canary instance, monitors it, then raises the share. Clients only ever know the public path; the migration is invisible to them.