Nginx as API Gateway — High-Performance Reverse Proxy and Load Balancer

In this tutorial, you will learn about Nginx as API Gateway. We cover key concepts, practical examples, and best practices to help you master this topic.

Nginx is a high-performance web server that functions as an API gateway through reverse proxying, rate limiting, SSL termination, caching, and access control directives configured in its powerful configuration language.

What You'll Learn

• Nginx as a reverse proxy for microservices
• Rate limiting with limit_req and limit_conn
• Caching, SSL termination, and basic auth in Nginx

Why It Matters

Nginx is battle-tested at internet scale, handling millions of concurrent connections with minimal resource usage. Using Nginx as your API gateway avoids introducing new infrastructure — teams already running Nginx can add gateway features without deploying new services.

Real-World Use

Durga Antivirus Pro uses Nginx as the first-layer gateway before Kong. Nginx handles SSL termination, rate limiting at the edge, and serves cached static threat definitions. Requests that pass these checks are forwarded to Kong for routing and plugin processing.

flowchart LR
    Client["Client"] --> Nginx["Nginx\nEdge Gateway"]
    Nginx -->|"Static content"| Cache["Cache"]
    Nginx -->|"API requests"| Kong["Kong Gateway"]
    Nginx -->|"Health checks"| Backend["Backend"]
    style Nginx fill:#dbeafe,stroke:#2563eb

Nginx as Reverse Proxy

http {
    upstream user_service {
        server user-srv-1:8080 weight=3;
        server user-srv-2:8080 weight=2;
        server user-srv-3:8080 backup;
    }

    server {
        listen 80;
        server_name api.dodatech.com;

        location /api/users/ {
            proxy_pass http://user_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;
        }

        location /api/orders/ {
            proxy_pass http://order_service/;
        }
    }
}

Rate Limiting with Nginx

http {
    # Define rate limit zone: 100 req/min per IP
    limit_req_zone $binary_remote_addr zone=api_limit:10m rate=100r/m;

    server {
        location /api/ {
            limit_req zone=api_limit burst=20 nodelay;
            proxy_pass http://backend;
        }

        # Stricter limit for login endpoint
        location /api/login {
            limit_req zone=login_limit:10m rate=5r/m burst=10;
            proxy_pass http://auth_service;
        }
    }
}

SSL Termination

server {
    listen 443 ssl http2;
    server_name api.dodatech.com;

    ssl_certificate /etc/letsencrypt/live/api.dodatech.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.dodatech.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    location / {
        proxy_pass http://backend;
    }
}

# Redirect HTTP to HTTPS
server {
    listen 80;
    server_name api.dodatech.com;
    return 301 https://$server_name$request_uri;
}

Response Caching

http {
    proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=api_cache:10m
                     max_size=1g inactive=60m;

    server {
        location /api/products/ {
            proxy_cache api_cache;
            proxy_cache_valid 200 5m;
            proxy_cache_valid 404 1m;
            proxy_cache_use_stale error timeout updating;
            add_header X-Cache-Status $upstream_cache_status;
            proxy_pass http://product_service;
        }
    }
}

Common Mistakes

1. Missing the Trailing Slash in proxy_pass

proxy_pass http://backend/users; vs proxy_pass http://backend/users/; — the trailing slash controls whether the matched location prefix is replaced. Misunderstanding this causes routing errors.

2. Not Tuning worker_processes

Default worker_processes auto may not work optimally. Set to match CPU core count for best performance.

3. Insufficient Rate Limit Zone Size

The 10m in limit_req_zone stores 160,000 IP states at 64 bytes each. For high-traffic APIs, increase this to 100m.

4. Overly Permissive SSL Ciphers

Supporting old ciphers for compatibility weakens security. Restrict to modern ciphers and TLS 1.2+.

5. No Health Checks for Upstreams

Nginx does not automatically remove dead upstreams without health checks. Use ngx_http_upstream_module health checks or a separate health monitoring tool.

Practice Questions

1. How does Nginx's proxy_pass directive route requests to upstream services?
2. What is the difference between rate=r/m and burst in limit_req?
3. Why must HTTP be redirected to HTTPS in Nginx?
4. What does proxy_cache_use_stale do and why is it useful?
5. How does Nginx handle Load Balancing across multiple upstream servers?

Answers:

1. proxy_pass specifies the backend URL. With a path, Nginx replaces the matched location portion. Without a path, it passes the full request URI.
2. rate sets the sustained request rate. burst allows short spikes above the rate by queuing excess requests, served at the defined rate.
3. HTTP redirects ensure all traffic is encrypted. Users who type http:// or follow old links are redirected to the secure version.
4. It serves stale cached content when the backend is unreachable or returning errors, maintaining availability during outages.
5. Nginx uses round-robin by default. Directives like weight, least_conn, ip_hash, and random configure different algorithms.

Challenge: Configure Nginx as an API gateway for three microservices with rate limiting, SSL termination, caching, and basic auth for the admin route. Test with curl.

FAQ

Mini Project

Configure Nginx as an API gateway for three backend services running on ports 8081, 8082, and 8083. Implement path-based routing, rate limiting (50 req/min per IP), SSL termination with a self-signed cert, and add X-Upstream: <name> header to responses.

What's Next

Continue with Envoy Proxy Gateway for a modern high-performance proxy, or explore WebSocket Gateway Support for real-time communication.