API routing with location blocks in Nginx - Step-by-Step Execution

Process Flow - API routing with location blocks

Client sends HTTP request

↓

Nginx receives request

↓

Check location blocks in order

↓

Match found?

No→Return 404 or default

Yes↓

Route request to matched location

↓

Serve response from backend or static files

Nginx receives a request, checks location blocks in order, routes to the matching block, or returns default if none match.

Execution Sample

Nginx

server {
  listen 80;
  location /api/ {
    proxy_pass http://backend_api;
  }
  location / {
    root /var/www/html;
  }
}

Routes requests starting with /api/ to backend_api, others serve static files from /var/www/html.

Process Table

Step	Request URI	Location Block Checked	Match Result	Action Taken
1	/api/users	location /api/	Match	Proxy to backend_api
2	/api/users	location /	Not checked (first match found)	No action
3	/home	location /api/	No match	Check next location
4	/home	location /	Match	Serve static files from /var/www/html
5	/unknown	location /api/	No match	Check next location
6	/unknown	location /	Match	Serve static files from /var/www/html
7	/notfound	location /api/	No match	Check next location
8	/notfound	location /	Match	Serve static files from /var/www/html

💡 Request routed to first matching location block or default if none match.

Status Tracker

Variable	Start	After Step 1	After Step 3	After Step 4	Final
Request URI		/api/users	/home	/home	/home
Matched Location	None	/api/	None	/	/
Action	None	Proxy to backend_api	None	Serve static files	Serve static files

Key Moments - 3 Insights

Why does Nginx stop checking location blocks after the first match?

Nginx uses the first matching location block to route the request, so once a match is found (see Step 1), it stops checking others to improve performance.

What happens if no location block matches the request URI?

If no location matches, Nginx uses the default server behavior, often returning a 404 error or serving the root location if defined (not shown in this example).

Why does /home match the location / block and not /api/?

Because /home does not start with /api/, so the /api/ location block does not match (Step 3), but / matches all URIs, so it matches at Step 4.

Visual Quiz - 3 Questions

Look at the execution table, what action is taken for the request URI '/api/users' at Step 1?

A Serve static files

B Return 404 error

C Proxy to backend_api

D Check next location block

💡 Hint

Check the 'Action Taken' column at Step 1 in the execution_table.

At which step does the request URI '/home' match the location block '/'?

A Step 3

B Step 4

C Step 2

D Step 1

💡 Hint

Look at the 'Match Result' column for '/home' in the execution_table.

If a new location block 'location /api/v2/' is added before 'location /api/', which request URI would match it first?

A /api/v2/items

B /home

C /api/users

D /api/

💡 Hint

Consider prefix matching order and the execution flow of location blocks.

Concept Snapshot

Nginx API routing uses location blocks to match request URIs.
The first matching location block handles the request.
Use prefix matching like 'location /api/' for API routes.
Order matters: more specific blocks should come first.
Unmatched requests go to default or return 404.

Full Transcript

When a client sends an HTTP request, Nginx receives it and checks its location blocks in order. It compares the request URI to each location block's prefix. Once it finds a match, it routes the request accordingly, such as proxying to a backend API or serving static files. If no location matches, Nginx returns a default response or error. For example, requests starting with '/api/' go to the backend API, while others serve static content. This process stops at the first match to keep routing efficient.

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