# API Gateway (for Frontends)

> Single entry point that routes, authenticates, and rate-limits across services.

Frontend architecture guidance from fearchitect, written by Abas Turabli and last reviewed 2026-06-21. Source: https://fearchitect.com/topics/api-gateway

Use it as reference for the task at hand. Before changing code, check this guidance against the codebase: where the code already makes a different, deliberate choice, flag the conflict instead of rewriting it. Library APIs move faster than this guide, so confirm exact signatures in the official docs linked at the end.

## Summary

An API gateway sits in front of every backend service and handles cross-cutting concerns — routing, TLS termination, auth, rate limiting, and observability — in one place. Services behind it stay simple because they don't each re-implement those concerns. Kong, AWS API Gateway, and Nginx are common implementations.

## API gateway

An API gateway is a reverse proxy that all client traffic passes through before reaching any service. It owns concerns that would otherwise be duplicated across every service: TLS termination, JWT or API-key validation, rate limiting per consumer, request routing, and response aggregation.

The gateway is shared infrastructure for all clients — mobile, web, and third-party consumers hit the same gateway. Edge/CDN gateways (Cloudflare Workers, AWS CloudFront Functions) push routing and light auth to the network edge, cutting latency before traffic reaches your origin.

## Diagram

```mermaid
graph TD
  MobileApp["Mobile client"]
  WebApp["Web client"]
  ThirdParty["Third-party consumer"]

  GW["API Gateway
(TLS · Auth · Rate limit · Routing)"]

  SvcA["Orders service"]
  SvcB["Users service"]
  SvcC["Inventory service"]

  MobileApp --> GW
  WebApp --> GW
  ThirdParty --> GW

  GW --> SvcA
  GW --> SvcB
  GW --> SvcC
```

All clients enter through the shared gateway; downstream services receive only pre-validated, routed requests.

## Decision: Gateway vs BFF

A gateway is shared policy infrastructure — it routes and enforces auth and rate limits for every client. A BFF (Backend for Frontend) is a per-client server that shapes and aggregates data for one client type.

They coexist: the gateway handles ingress and policy; a BFF per client sits behind it for client-specific composition. Don't put client-specific response shaping in the shared gateway.

## Request pipeline through the gateway

### 1. TLS termination

The gateway decrypts the incoming HTTPS connection. Internal service-to-service traffic may use plain HTTP, centralising certificate management in one place.

### 2. Auth

Validates a JWT or API key, attaches an identity claim to the forwarded request, and rejects unauthenticated calls before they reach any service.

### 3. Rate limiting

Counts requests per consumer against a token-bucket or sliding-window counter stored in Redis. Exceeding the quota returns 429 without hitting the upstream.

### 4. Routing

Matches the URL path or hostname to a registered upstream and proxies the request, optionally rewriting path prefixes.

### 5. Observability

Emits a request log, latency metric, and trace span for every call — one place to get network-level visibility across all services.

## Kong route with JWT auth and rate limiting

Kong applies cross-cutting concerns as plugins on a route. The Orders service never sees unauthenticated or over-quota traffic — the gateway drops those requests first.

**Kong declarative config — JWT auth + rate limiting on /api/orders**

```yaml
# kong.yml
services:
  - name: orders-service
    url: http://orders-svc:3000
    routes:
      - name: orders-route
        paths: ["/api/orders"]
    plugins:
      - name: jwt          # validates Bearer token, rejects 401 if invalid
      - name: rate-limiting
        config:
          minute: 100      # 100 req/min per consumer key
          policy: redis
```

Kong applies JWT validation and rate limiting as plugins on the route — the Orders service receives only authenticated, quota-checked requests.

## Gateway trade-offs

**Pros**

- Auth, rate limiting, and TLS live in one place — not duplicated per service.
- Services receive pre-validated requests, reducing per-service boilerplate.
- Centralized observability: one place to emit logs, metrics, and traces.
- Consumer-level quota enforcement without touching service code.
- Canary and blue/green routing changes deploy without redeploying services.

**Cons**

- Single point of failure — must run multiple redundant instances.
- Adds one network hop and serialisation overhead per request.
- A misconfigured auth plugin exposes all services at once.
- Plugin ecosystems vary in capability; complex transforms may not fit natively.
- Shared config can become a deployment bottleneck when every team needs changes.

## Key terms

- **API gateway**: Reverse proxy handling auth, routing, rate limiting, and TLS for all clients across all services.
- **BFF (Backend for Frontend)**: Per-client server that aggregates and shapes data specifically for one client type.
- **TLS termination**: Gateway decrypts HTTPS at the edge; internal service-to-service traffic may use plain HTTP.
- **Rate limiting**: Caps requests per consumer per time window, usually tracked in Redis via token-bucket or sliding-window.
- **Edge gateway**: Gateway deployed on CDN infrastructure (e.g., Cloudflare Workers) to enforce policy before traffic hits origin.

## Related topics

- [Backend for Frontend (BFF)](https://fearchitect.com/topics/backend-for-frontend.md): A per-client server layer that shapes and aggregates APIs for one frontend.
- [CDN & Edge Caching](https://fearchitect.com/topics/cdn-edge-caching.md): Serve cached responses from PoPs near users, sparing the origin.
- [Edge Computing & Rendering](https://fearchitect.com/topics/edge-computing-rendering.md): Run code at CDN PoPs to cut latency before origin is hit.
- [Load Balancing (for Frontends)](https://fearchitect.com/topics/load-balancing.md): Spread traffic across servers; keep WebSocket apps sticky.
- [Auth: OAuth, JWT & Sessions](https://fearchitect.com/topics/auth-oauth-jwt-sessions.md): Delegate identity with OAuth, carry claims in JWTs, store state in sessions.
- [Component Architecture & Project Structure](https://fearchitect.com/topics/component-architecture.md): Structuring components so composition beats configuration.

## Further reading

- [Kong — What is an API Gateway?](https://konghq.com/learning-center/api-gateway/what-is-an-api-gateway)
- [AWS — What is Amazon API Gateway?](https://docs.aws.amazon.com/apigateway/latest/developerguide/welcome.html)
- [Cloudflare Workers docs](https://developers.cloudflare.com/workers/)
- [Microsoft — Gateway Routing pattern](https://learn.microsoft.com/en-us/azure/architecture/patterns/gateway-routing)