Course contentsShow
← System Design
Lesson 892 of 1,91923. API Gateway PatternFree lesson

API Versioning and Routing

Managing multiple API versions and routing requests to appropriate service versions based on headers or paths.

API Versioning and Routing

You'll learn how to manage multiple API versions simultaneously and intelligently route requests to the correct service version without breaking existing clients.

Why API Versioning Matters

As your system evolves, you'll need to introduce breaking changes—new field requirements, restructured responses, or deprecated endpoints. But you can't force all clients to upgrade immediately. API versioning lets old and new clients coexist peacefully by routing each request to the appropriate version of your backend services.

The API Gateway is the perfect place to handle this routing logic, keeping version complexity out of your microservices.

Common Versioning Strategies

Path-based versioning embeds the version in the URL:

  • /v1/users routes to service version 1
  • /v2/users routes to service version 2

Header-based versioning uses HTTP headers:

  • Accept: application/vnd.myapi.v1+json signals version 1
  • Api-Version: 2 explicitly requests version 2

The Gateway inspects these indicators and routes accordingly. Think of it like a postal sorting facility: letters (requests) arrive with addresses (version info), and the facility ensures each reaches the correct destination (service version).

Routing Implementation

Your Gateway maintains routing rules that map version identifiers to backend service instances or clusters. When a request arrives, the Gateway:

  1. Extracts the version from path or header
  2. Looks up the corresponding routing rule
  3. Forwards the request to the appropriate service version
  4. May transform the response if formats differ

This approach lets you run multiple service versions simultaneously, gradually migrate clients, and deprecate old versions on your timeline.

Key Takeaway: API versioning at the Gateway decouples client upgrade cycles from backend evolution, enabling backward compatibility through intelligent routing based on paths or headers.