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.

Practice

1. What does a location block in an nginx configuration do?

easy

A. Sets the maximum file upload size

B. Defines server IP addresses

C. Specifies the server's operating system

D. Routes incoming requests based on URL paths

Solution

1. Step 1: Understand the purpose of location blocks

   Location blocks in nginx are used to match parts of the URL path to decide how to handle requests.

2. Step 2: Identify what location blocks control

   They control routing of requests to different handlers or backends based on the URL.

3. Final Answer:

   Routes incoming requests based on URL paths -> Option D

4. Quick Check:

   Location blocks = URL routing [OK]

Hint: Location blocks match URL paths to route requests [OK]

Common Mistakes:

• Confusing location blocks with server IP settings
• Thinking location blocks set server OS
• Assuming location blocks control upload size

2. Which of the following is the correct syntax to define a location block that matches exactly the path /api/v1/users?

easy

A. location = /api/v1/users { ... }

B. location /api/v1/users { ... }

C. location ~ /api/v1/users { ... }

D. location ^~ /api/v1/users { ... }

Solution

1. Step 1: Recall nginx location modifiers

   The = modifier means exact match of the URL path.

2. Step 2: Match the exact path syntax

   Using location = /api/v1/users matches only that exact path.

3. Final Answer:

   location = /api/v1/users { ... } -> Option A

4. Quick Check:

   Exact match uses = modifier [OK]

Hint: Use '=' for exact path match in location [OK]

Common Mistakes:

• Using no modifier for exact match
• Using regex (~) when exact match needed
• Using ^~ which is prefix but not exact

3. Given this nginx config snippet:

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

What happens when a client requests /api/users?

medium

A. Request is forwarded to http://backend-service/users

B. Request is forwarded to http://backend-service/api/users

C. Request is served locally from /api/users directory

D. Request returns 404 Not Found

Solution

1. Step 1: Understand proxy_pass with trailing slash

   When proxy_pass URL ends with a slash, nginx replaces the matching part of the request URI.

2. Step 2: Apply to the request path

   The matching prefix /api/ is replaced by / from proxy_pass, so /api/users becomes /users at backend.

3. Final Answer:

   Request is forwarded to http://backend-service/users -> Option A

4. Quick Check:

   proxy_pass with trailing slash replaces prefix [OK]

Hint: Trailing slash in proxy_pass replaces matched prefix [OK]

Common Mistakes:

• Assuming proxy_pass appends full original URI
• Confusing local serving with proxying
• Ignoring trailing slash effect in proxy_pass

4. Identify the error in this nginx location block:

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

medium

A. Missing trailing slash in location path causes wrong proxying

B. location path should end with a slash to match subpaths

C. proxy_pass URL must not have a trailing slash

D. No error; configuration is correct

Solution

1. Step 1: Check location path matching behavior

   Without a trailing slash, location /api matches only the exact path /api and not subpaths like /api/users.

2. Step 2: Correct usage for subpath matching

   To match /api and all subpaths, use location /api/ with trailing slash.

3. Final Answer:

   location path should end with a slash to match subpaths -> Option B

4. Quick Check:

   Trailing slash in location matches subpaths [OK]

Hint: Add trailing slash in location to match subpaths [OK]

Common Mistakes:

• Thinking proxy_pass trailing slash is wrong here
• Assuming location without slash matches subpaths
• Believing config is error-free without checking path

5. You want to route all requests starting with /api/v2/ to http://v2-backend/ but requests exactly to /api/v2/status should return a static JSON response locally. Which nginx config achieves this?

hard

A. location /api/v2/status { return 200 '{"status":"ok"}'; }
location ^~ /api/v2/ { proxy_pass http://v2-backend/; }

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

C. location = /api/v2/status { return 200 '{"status":"ok"}'; }
location /api/v2/ { proxy_pass http://v2-backend/; }

D. location /api/v2/ { proxy_pass http://v2-backend/; }
location = /api/v2/status { proxy_pass http://v2-backend/status; }

Solution

1. Step 1: Use exact match for static response

   Use location = /api/v2/status to match exactly that path and return static JSON.

2. Step 2: Use prefix match for all other /api/v2/ requests

   Use location /api/v2/ to proxy all other requests to backend.

3. Final Answer:

   location = /api/v2/status { return 200 '{"status":"ok"}'; } location /api/v2/ { proxy_pass http://v2-backend/; } -> Option C

4. Quick Check:

   Exact match first, then prefix proxy [OK]

Hint: Exact match location before prefix for special cases [OK]

Common Mistakes:

• Placing prefix location before exact match causing override
• Using proxy_pass for static JSON response
• Not escaping JSON properly in return directive