Custom Header-Based Routing

In this lesson, you will learn how to direct incoming traffic to specific backend services or code paths by inspecting custom request headers.

The Concept

When building scalable systems, you often need to run multiple versions of an API simultaneously—perhaps to test a new feature with a subset of users (Canary deployment) or to support legacy clients. Instead of assigning different domain names or port numbers for every version, you can perform Custom Header-Based Routing at the entry point of your application.

By inspecting a request before it reaches your business logic, you can check for a custom header (e.g., X-API-Version) and route the request accordingly. This happens during the request pre-processing stage, allowing you to manipulate the request flow before it consumes significant resources.

Implementation Illustration

In a standard Node.js proxy or gateway, you can intercept the request object to determine where the traffic should land:

const http = require('http');

const server = http.createServer((req, res) => {
  // Inspect the custom header
  const version = req.headers['x-api-version'];

  if (version === '2.0') {
    // Route to the modern service logic
    routeToServiceV2(req, res);
  } else {
    // Default to the legacy/stable version
    routeToServiceV1(req, res);
  }
});

server.listen(8080);

Why it Matters

This approach is highly efficient for Request Shadowing or feature flagging. Because this check happens early in the request lifecycle, it acts as a lightweight traffic controller. It allows you to decouple your infrastructure from your business logic, meaning your clients don't need to change their URLs when you update your backend services.

When implementing this, ensure you define a clear naming convention for your headers and always provide a sensible fallback mechanism (default routing) for clients that do not provide the version header. By offloading this responsibility to the edge of your service, you maintain a cleaner, more modular architecture that is easier to debug and scale.

Key Takeaway: By inspecting custom headers during pre-processing, you create a flexible routing layer that enables seamless versioning and granular traffic control without modifying external client interfaces.