How do I route API requests by path or version?

There are a few common ways to route API requests by path or version, depending on whether you’re doing it in an API gateway, a backend framework, or a reverse proxy.

1) Route by path

This is the simplest approach.

Example

• GET /users → users service
• GET /orders → orders service
• POST /payments → payments service

Typical routing rule

• Match the request path prefix or exact path
• Send to the corresponding handler/service

Example in a reverse proxy style

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

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

---

2) Route by API version in the URL

This is very common for public APIs.

Example

• /api/v1/users
• /api/v2/users

Why use it

• Easy for clients to understand
• Simple to manage multiple versions simultaneously
• Works well with gateways and proxies

Example route pattern

• /api/v1/* → version 1 handlers
• /api/v2/* → version 2 handlers

Example in code

app.use('/api/v1', v1Router);
app.use('/api/v2', v2Router);

---

3) Route by version using headers

Instead of putting the version in the path, you can put it in a header:

Accept: application/vnd.myapi.v2+json

or

X-API-Version: 2

Why use it

• Cleaner URLs
• Useful when versioning should be hidden from the path

Downside

• Harder to test manually
• Less visible and sometimes less cache-friendly

---

4) Route by query parameter

Example:

• /users?version=2

Usually not ideal

It works, but it’s generally less preferred for API versioning because:

• It’s easy to miss
• It can be awkward for caching
• It’s less conventional than path or header versioning

---

5) Route by host/subdomain

Example:

• v1.api.example.com
• v2.api.example.com

Useful when

• You want strong separation between versions
• Different versions are deployed independently

---

Recommended approach

For most APIs, use:

• Path-based versioning: /api/v1/...
• Path-based routing for service boundaries: /users, /orders, etc.

This is the most straightforward and widely supported.

---

Practical routing pattern

A common structure is:

• /api/v1/users → user service, v1 controller
• /api/v1/orders → order service, v1 controller
• /api/v2/users → user service, v2 controller

That means:

1. First route by version
2. Then route by resource path

---

If you want, I can show you how to do this in a specific stack like Express, FastAPI, Spring Boot, Flask, Nginx, Kong, or AWS API Gateway.