API routing with location blocks in Nginx - Commands & Configuration

Introduction

When you run a web server, you often need to send different web requests to different parts of your app. Nginx uses location blocks to decide where to send each request based on the URL path. This helps organize your API routes clearly and efficiently.

When you want to send requests starting with /api/users to one backend service and /api/products to another.

When you need to serve static files from one folder and API requests from another.

When you want to add special rules for certain URL paths, like caching or authentication.

When you want to separate API routes from the main website routes in your server configuration.

When you want to proxy different API endpoints to different servers or ports.

Config File - nginx.conf

nginx.conf

events {}
http {
    server {
        listen 80;
        server_name example.com;

        location /api/users/ {
            proxy_pass http://localhost:3001/;
        }

        location /api/products/ {
            proxy_pass http://localhost:3002/;
        }

        location / {
            root /var/www/html;
            index index.html;
        }
    }
}

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

The location /api/users/ block sends requests starting with /api/users/ to a backend server running on localhost port 3001.

The location /api/products/ block sends requests starting with /api/products/ to another backend on localhost port 3002.

The location / block serves static files from /var/www/html for all other requests.

Commands

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

Terminal

sudo 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 /api/users/profile route to verify it is routed correctly to the backend on port 3001.

Terminal

curl -i http://example.com/api/users/profile

Expected Output

HTTP/1.1 200 OK

Server: nginx

Date: Wed, 01 Jan 2025 12:00:00 GMT

Content-Type: application/json

Content-Length: 123



{"user":"profile data"}

This command sends a request to the /api/products/list route to verify it is routed correctly to the backend on port 3002.

Terminal

curl -i http://example.com/api/products/list

Expected Output

HTTP/1.1 200 OK

Server: nginx

Date: Wed, 01 Jan 2025 12:00:01 GMT

Content-Type: application/json

Content-Length: 456



{"products":["item1","item2"]}

Key Concept

If you remember nothing else from this pattern, remember: location blocks in Nginx match URL paths to route requests to the right backend or content.

Common Mistakes

Forgetting the trailing slash in proxy_pass URL inside location blocks.

Without the trailing slash, Nginx appends the full original request URI, which can cause incorrect routing or duplicated paths.

Always include a trailing slash in proxy_pass like proxy_pass http://localhost:3001/; to correctly rewrite the URL.

Placing more general location blocks before specific ones.

Nginx matches location blocks in order and may use a general block before a specific one, causing wrong routing.

Put specific location blocks (like /api/users/) before general ones (like /) to ensure correct matching.

Not testing the configuration with nginx -t before reloading.

Syntax errors can cause Nginx to fail to reload, leading to downtime.

Always run sudo nginx -t to check syntax before reloading the server.

Summary

Use location blocks in Nginx to route different URL paths to different backends or content.

Test your Nginx configuration with nginx -t before reloading to avoid errors.

Reload Nginx to apply changes without stopping the server.

Verify routing by sending requests to your API endpoints and checking responses.