API versioning with routing in Nginx - Commands & Configuration

Introduction

When you update an API, old clients might still use the previous version. API versioning with routing helps direct requests to the correct version so everyone gets the right response without breaking.

When you want to support multiple versions of an API at the same time.

When you need to upgrade your API without forcing all users to update immediately.

When you want to test a new API version while keeping the old one live.

When different clients require different API versions based on their capabilities.

When you want to organize your API endpoints clearly by version.

Config File - nginx.conf

nginx.conf

events {}

http {
    upstream backend-v1 {
        server 127.0.0.1:8081;
    }

    upstream backend-v2 {
        server 127.0.0.1:8082;
    }

    server {
        listen 80;

        location /api/v1/ {
            proxy_pass http://backend-v1/;
        }

        location /api/v2/ {
            proxy_pass http://backend-v2/;
        }
    }
}

This configuration sets up an Nginx server listening on port 80.

Requests starting with /api/v1/ are routed to the backend server at 127.0.0.1:8081, which serves version 1 of the API.

Requests starting with /api/v2/ are routed to the backend server at 127.0.0.1:8082, which serves version 2 of the API.

The upstream blocks define the backend servers for each API version.

Commands

This command tests the Nginx configuration file for syntax errors before applying it.

Terminal

nginx -t

Expected Output

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok

nginx: configuration file /etc/nginx/nginx.conf test is successful

This command reloads Nginx to apply the new configuration without stopping the server.

Terminal

sudo systemctl reload nginx

Expected Output

No output (command runs silently)

This command sends a request to the version 1 API endpoint to verify routing works correctly.

Terminal

curl -i http://localhost/api/v1/users

Expected Output

HTTP/1.1 200 OK

Content-Type: application/json



{"version":"v1","users":[]}

This command sends a request to the version 2 API endpoint to verify routing works correctly.

Terminal

curl -i http://localhost/api/v2/users

Expected Output

HTTP/1.1 200 OK

Content-Type: application/json



{"version":"v2","users":[]}

Key Concept

If you remember nothing else from this pattern, remember: use URL paths to route requests to different API versions so clients get the right backend response.

Common Mistakes

Not testing the Nginx configuration before reloading.

This can cause Nginx to fail to reload and stop serving requests.

Always run 'nginx -t' to check for syntax errors before reloading.

Using the same backend server for all API versions without routing.

Clients will not get the correct API version responses, causing errors or confusion.

Define separate upstream servers and route requests based on the version in the URL.

Forgetting the trailing slash in location paths like '/api/v1/'.

This can cause incorrect routing or missing resources.

Include the trailing slash in location blocks to match the URL path correctly.

Summary

Define separate location blocks in Nginx for each API version using URL paths.

Use upstream blocks to point to different backend servers for each API version.

Test the Nginx configuration with 'nginx -t' before reloading to avoid downtime.

Reload Nginx to apply the new routing rules without stopping the server.

Verify routing by sending requests to each API version URL and checking responses.