Nginx as an API Gateway

Analogy categoryAnalogies

An API gateway sits in front of one or more backend services and handles cross-cutting concerns — routing, authentication, rate limiting, load balancing, and request/response transformation — so individual services don't each reimplement them. While dedicated gateway products like Kong or Amazon API Gateway exist, Nginx's location blocks, upstream module, and rich directive set make it entirely capable of playing this role for a large share of real-world microservice architectures, especially where you already run Nginx as your reverse proxy and want to avoid adding another moving part to the stack.

🏏

Cricket analogy: An API gateway routing requests to the right microservice is like a captain like Rohit Sharma deciding which bowler to bring on for each over based on the batter and match situation.

Routing and Load Balancing with the upstream Block

The core building block is the upstream directive, which names a pool of backend servers, and location blocks that map URL paths to those pools. Nginx supports several load-balancing algorithms out of the box: round_robin (the default), least_conn (send to the server with fewest active connections), and ip_hash (sticky routing based on client IP), plus weighted distribution by adding a weight parameter to individual servers. Health is managed passively by default — Nginx marks a server as unavailable after max_fails failures within fail_timeout — and Nginx Plus adds active health checks, though open-source deployments commonly pair Nginx with an external health-checking sidecar for that purpose.

🏏

Cricket analogy: least_conn routing to the server with fewest active connections is like a captain rotating bowlers to whoever has bowled fewest overs that spell, keeping workload balanced across the attack.

Rate Limiting and Authentication at the Edge

The limit_req_zone and limit_req directives implement token-bucket rate limiting keyed on any variable, most commonly $binary_remote_addr, letting you cap requests per second per client IP and absorb short bursts with the burst parameter, optionally smoothing them with nodelay. For authentication, Nginx can enforce basic auth with auth_basic, validate JWTs using the njs scripting module or the commercial auth_jwt directive in Nginx Plus, or delegate to an upstream auth check using auth_request, which sends a subrequest to a dedicated auth microservice and only proceeds if it returns 2xx — a pattern widely used to centralize token validation without duplicating it in every backend service.

🏏

Cricket analogy: Rate limiting with a burst allowance is like a bowler permitted a couple of no-balls before a warning, but a sustained pattern of overstepping triggers an official over-rate penalty.

The auth_request pattern is powerful because it decouples authentication logic from every individual backend service: you write and maintain the token-validation logic once in a small auth microservice, and every location block that needs protection simply adds auth_request /auth; pointing at it.

Request Transformation and Versioning

Nginx can rewrite paths, strip or add headers, and route by version prefix or Accept header, letting you present a stable public API surface while backend services evolve independently. A common pattern maps /v1/users/ to one upstream and /v2/users/ to a newer one during a migration, using proxy_pass with trailing slashes to control whether the matched prefix is stripped. proxy_set_header lets you inject or forward headers like X-Request-Id for tracing, and add_header can attach CORS or security headers uniformly across every API response without each backend service implementing them itself.

🏏

Cricket analogy: Routing /v1/ and /v2/ traffic to different backends is like a franchise fielding its old-format T20 squad and a newer format squad in parallel during a rules transition period.

proxy_pass path-stripping behavior is a common source of bugs: location /api/ { proxy_pass http://backend/; } strips the /api/ prefix (trailing slash on both sides), while omitting the trailing slash on proxy_pass forwards the full original path. Test both variants explicitly, since the wrong combination silently sends requests to the wrong backend route.

nginx

http {
    upstream users_service {
        least_conn;
        server 10.0.1.10:8080 weight=3;
        server 10.0.1.11:8080;
        server 10.0.1.12:8080 backup;
    }

    limit_req_zone $binary_remote_addr zone=api_limit:10m rate=10r/s;

    server {
        listen 443 ssl;
        server_name api.example.com;

        location /v2/users/ {
            limit_req zone=api_limit burst=20 nodelay;
            auth_request /auth;

            proxy_pass http://users_service/;
            proxy_set_header X-Request-Id $request_id;
            add_header Access-Control-Allow-Origin "*";
        }

        location = /auth {
            internal;
            proxy_pass http://auth_service/validate;
            proxy_pass_request_body off;
        }
    }
}

Nginx can act as an API gateway using upstream blocks for load balancing and location blocks for routing to backend services.
Load-balancing algorithms include round_robin (default), least_conn, ip_hash, and weighted distribution.
limit_req_zone and limit_req implement token-bucket rate limiting per client, with burst and nodelay controlling tolerance for spikes.
auth_request delegates authentication to a dedicated microservice via subrequest, centralizing token validation without duplicating it in every backend.
Path-based or header-based routing supports API versioning by directing /v1/ and /v2/ traffic to different upstream pools.
proxy_pass trailing-slash behavior controls whether the matched location prefix is stripped before forwarding — a frequent source of misrouted requests.
add_header and proxy_set_header let you uniformly inject tracing, CORS, and security headers at the gateway instead of in every service.