API Gateway

Introduction

An API Gateway is the single entry point for client applications (mobile, web, partners) into your microservice ecosystem. Beyond routing, it centralizes cross-cutting concerns: authentication, rate limiting, request transformation, API versioning, and response aggregation (BFF pattern).

Without a gateway, every service would expose public endpoints, duplicate auth logic, and leak internal topology. Kong, AWS API Gateway, Spring Cloud Gateway, and Envoy-based ingress controllers are common implementations.

This lesson positions the gateway in HLD, contrasts it with load balancers and service mesh, and covers BFF patterns for mobile vs web clients.

Understanding the topic

Key concepts

• Edge authentication: validate JWT/OAuth2 before forwarding to internal services.
• Rate limiting and quota enforcement per API key or user tier.
• Request/response transformation: JSON ↔ gRPC, field filtering for mobile payloads.
• API composition: one mobile screen calls one gateway endpoint aggregating 3 services.
• Version routing: /v1 → legacy cluster, /v2 → new cluster (canary).
• Not a replacement for service mesh — gateway is north-south; mesh is east-west.

flowchart TB
  Mobile --> GW[API Gateway]
  Web --> GW
  GW --> Auth
  GW --> Orders
  GW --> Catalog

Internal architecture

Architecture overview

flowchart TB
  Mobile --> GW[API Gateway]
  Web --> GW
  GW --> Auth
  GW --> Orders
  GW --> Catalog

Step-by-step explanation

1. Mobile/Web → CDN (static) + API Gateway (dynamic API).
2. Gateway plugins/filters: auth → rate limit → route → circuit breaker → upstream service.
3. Internal services on private network; only gateway has public ingress.
4. Optional BFF services per client type behind dedicated gateway routes.
5. Centralized OpenAPI docs and developer portal for partner APIs.
6. Observability: gateway emits access logs, metrics per route, trace root span.

Informative example

Spring Cloud Gateway route with JWT validation and Redis rate limiter:

spring:
  cloud:
    gateway:
      routes:
        - id: orders
          uri: lb://order-service
          predicates:
            - Path=/api/v1/orders/**
          filters:
            - name: RequestRateLimiter
              args:
                redis-rate-limiter.replenishRate: 100
                redis-rate-limiter.burstCapacity: 200
                key-resolver: "#{@userKeyResolver}"
            - TokenRelay=
            - name: CircuitBreaker
              args:
                name: orderCb
                fallbackUri: forward:/fallback/orders

  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://auth.example.com/realms/shop

Gateway validates JWT once; internal services trust mTLS or internal network. Rate limit key = userId or API key.

Real-world use

Real-world use cases

• Fintech mobile app: gateway aggregates balance, transactions, offers in one call.
• Partner B2B e-commerce: API keys, quotas, webhook registration at gateway.
• OTT: device-specific BFF routes optimize payload for TV vs phone.
• Healthcare patient portal: gateway enforces OAuth scopes before PHI services.

Best practices

• Keep gateway thin — no heavy business logic; use BFF services if aggregation complex.
• Propagate trace and auth headers to downstream (X-Request-Id, Authorization).
• Configure timeouts per route matching downstream SLOs.
• Use circuit breakers and fallbacks for graceful degradation.
• Document breaking changes with versioned paths.
• Separate public partner gateway from internal admin ingress.

Common mistakes

• God gateway with business rules — becomes distributed monolith choke point.
• No timeout — slow service hangs all client requests.
• Double auth validation overhead without caching JWKS keys.
• Exposing internal service URLs in error responses.
• Rate limit only by IP — shared NAT blocks legitimate users.

Advanced interview questions

Summary

API Gateway is the secure front door for microservices. Centralizes auth, rate limits, routing, and versioning. BFF pattern optimizes payloads per client type. Keep business logic in services, not gateway plugins. Pair with service mesh for internal mTLS and retries. CDN offloads static content complementary to gateway.