API versioning with routing in Nginx - Step-by-Step Execution

Process Flow - API versioning with routing

Client sends request

↓

Nginx receives request

↓

Check URL path for version

↓

/v1/*

↓

Route to v1 backend

↓

Backend processes request

↓

Response sent back to client

Nginx checks the request URL path for version info and routes to the matching backend service.

Execution Sample

Nginx

location /v1/ {
    proxy_pass http://backend_v1;
}
location /v2/ {
    proxy_pass http://backend_v2;
}

Routes requests with /v1/ to backend_v1 and /v2/ to backend_v2.

Process Table

Step	Request URL	Version Detected	Routing Action	Backend Target
1	/v1/users	/v1	Route to /v1 location block	backend_v1
2	/v2/orders	/v2	Route to /v2 location block	backend_v2
3	/v3/products	No match	Default routing or 404	No backend
4	/v1/status	/v1	Route to /v1 location block	backend_v1
5	/api/v2/data	No match	Default routing or 404	No backend

💡 Requests without matching version prefix are not routed to versioned backends.

Status Tracker

Variable	Start	After Step 1	After Step 2	After Step 3	After Step 4	After Step 5
Request URL		/v1/users	/v2/orders	/v3/products	/v1/status	/api/v2/data
Version Detected		/v1	/v2	No match	/v1	No match
Backend Target		backend_v1	backend_v2	No backend	backend_v1	No backend

Key Moments - 2 Insights

Why does the request to /v3/products not route to any backend?

Because the execution_table row 3 shows no version prefix match, nginx does not find a location block for /v3/, so it uses default routing or returns 404.

Why does /api/v2/data not route to backend_v2 even though it contains 'v2'?

The routing matches only if the URL path starts exactly with /v2/. Since /api/v2/data does not start with /v2/, it does not match the /v2/ location block (see execution_table row 5).

Visual Quiz - 3 Questions

Look at the execution_table, what backend does the request to /v1/status route to?

A No backend

B backend_v1

C backend_v2

D Default backend

💡 Hint

Check execution_table row 4 under Backend Target column.

At which step does the version detection fail to find a matching version prefix?

A Step 3

B Step 1

C Step 4

D Step 2

💡 Hint

Look at the Version Detected column in execution_table for 'No match'.

If we add a location block for /v3/, what would happen to the request at step 3?

A It would still return 404

B It would route to backend_v1

C It would route to backend_v3

D It would route to backend_v2

💡 Hint

Adding a matching location block routes requests to that backend (see concept_flow).

Concept Snapshot

API versioning with routing in nginx:
- Use location blocks matching version prefixes like /v1/, /v2/
- Requests matching /v1/* route to backend_v1
- Requests matching /v2/* route to backend_v2
- Requests without matching prefix use default or 404
- This cleanly separates API versions by URL path

Full Transcript

This visual execution shows how nginx routes API requests based on version prefixes in the URL path. When a client sends a request, nginx checks the URL path for version segments like /v1/ or /v2/. It then routes the request to the corresponding backend service configured in location blocks. Requests that do not match any version prefix are routed to default or return 404. The execution table traces requests step-by-step, showing detected version and backend target. The variable tracker shows how request URL, detected version, and backend target change per request. Key moments clarify why some requests do not route to any backend. The quiz tests understanding of routing decisions based on the execution visuals. This method helps maintain multiple API versions cleanly and safely.