Reverse proxies for APIs: headers, timeouts, body size, and cache

The proxy is an operational layer#

Production traffic commonly passes through a CDN, load balancer, or reverse proxy before it reaches the app. If the proxy is wrong, correct application code can still fail.

Forwarded headers#

Applications often need the original host, scheme, and client IP. Proxies should forward the right headers, and applications should trust only known proxy sources.

location / {
  proxy_pass http://app:3000;
  proxy_set_header Host $host;
  proxy_set_header X-Forwarded-Proto $scheme;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Request-Id $request_id;
}

Timeouts and body size#

Timeouts must align across client, proxy, app, database, and internal HTTP clients. Body size limits should match endpoint needs. For large uploads, prefer direct uploads to object storage with signed URLs.

Cache policy#

Public blog content, static assets, and RSS can often be cached. Admin dashboards, user-specific APIs, authorization responses, and cookie-bearing responses should not be cached by shared proxies.

• public: shared caches may store the response.
• private: only the end user's browser should store it.
• no-store: do not store the response.
• s-maxage: TTL for shared caches such as CDNs.

Checklist#

• Host, scheme, and client IP headers are forwarded correctly.
• The app trusts only known proxy headers.
• Proxy and app timeouts do not contradict each other.
• Body size limits match each endpoint.
• Public cache is not applied to private data.
• Logs include request ID, status, path, and upstream time.

Primary references#

• NGINX Docs: HTTP proxy module
• MDN: Cache-Control
• MDN: X-Forwarded-For