How to Use NGINX as an API Gateway: Simple Guide

Use nginx as an API gateway by configuring server blocks with location directives to proxy API requests to backend services. Set up proxy_pass to forward requests, and optionally add features like rate limiting, authentication, and caching.

Syntax

The basic syntax to use NGINX as an API gateway involves defining a server block that listens on a port and uses location blocks to route requests to backend APIs. The key directive is proxy_pass, which forwards client requests to the target API service.

• server {}: Defines the virtual server.
• listen: Specifies the port NGINX listens on.
• location /path/ {}: Matches request paths to route.
• proxy_pass http://backend/;: Forwards requests to backend API.

nginx

server {
    listen 80;

    location /api/ {
        proxy_pass http://backend-service/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Example

This example shows NGINX acting as an API gateway that listens on port 8080 and forwards all requests starting with /api/ to a backend service running on http://localhost:5000. It also sets headers to preserve client information.

nginx

server {
    listen 8080;

    location /api/ {
        proxy_pass http://localhost:5000/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
    }
}

Output

When a client sends a request to http://your-nginx-server:8080/api/users, NGINX forwards it to http://localhost:5000/users preserving headers.

Common Pitfalls

Common mistakes when using NGINX as an API gateway include:

• Forgetting the trailing slash in proxy_pass, which can cause incorrect URL forwarding.
• Not setting necessary headers like X-Forwarded-For to preserve client IP.
• Ignoring connection headers causing backend connection issues.
• Not handling CORS headers if APIs are accessed from browsers.

nginx

server {
    listen 80;

    location /api/ {
        # Wrong: missing trailing slash causes path issues
        proxy_pass http://backend-service;
    }
}

# Correct version:
server {
    listen 80;

    location /api/ {
        proxy_pass http://backend-service/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Quick Reference

Key directives for using NGINX as an API gateway:

Directive	Purpose
proxy_pass	Forward requests to backend API service
proxy_set_header	Set or modify HTTP headers sent to backend
location	Match request URI paths for routing
listen	Define port NGINX listens on
limit_req_zone / limit_req	Rate limiting to protect APIs
auth_basic / auth_basic_user_file	Basic authentication for API access control

Key Takeaways

Use proxy_pass with a trailing slash to correctly forward API requests.

Set headers like X-Forwarded-For to preserve client IP information.

Configure location blocks to route different API paths to appropriate backends.

Beware of CORS and connection header issues when proxying APIs.

NGINX can add features like rate limiting and authentication to secure your API gateway.