Course contentsShow
← System Design
Lesson 1907 of 1,91945. API Design and VersioningFree lesson

Gateway-Level Version Routing

Using API gateways to route requests to different backend versions based on client version.

Gateway-Level Version Routing

What you'll learn: How API gateways can intelligently route incoming requests to different backend service versions based on client-specified version information.

The Core Idea

Gateway-level version routing centralizes version management at the API gateway layer rather than forcing each backend service to handle multiple versions internally. When a request arrives, the gateway examines version indicators (URI path, headers, or query parameters) and routes the request to the appropriate backend service version—think of it as a smart postal service that reads addresses and delivers mail to different buildings based on apartment numbers.

How It Works

The API gateway acts as a single entry point. When a client makes a request like GET /v2/users, the gateway:

  1. Parses the version indicator (v2 in the path)
  2. Looks up routing rules in its configuration
  3. Forwards the request to the backend cluster running version 2 of the API
  4. Returns the response to the client

This approach allows you to run multiple backend versions simultaneously (e.g., api-v1.internal:8080 and api-v2.internal:8080) without clients knowing about internal infrastructure.

Benefits

  • Isolation: Each version runs independently; crashes in v2 don't affect v1
  • Gradual migration: Route 10% of v2 traffic to test before full rollout
  • Clean separation: Backend services focus on business logic, not version negotiation
  • Centralized policies: Apply rate limiting, authentication differently per version

Example Routing Rules

The gateway configuration might specify: requests with /v1/* → backend cluster A, requests with /v2/* → backend cluster B, header API-Version: 3 → backend cluster C.

Key Takeaway: Gateway-level version routing decouples client-facing version indicators from backend deployment topology, enabling independent scaling, testing, and deprecation of API versions through centralized traffic management.