API Gateway Complete Guide

GET /api/users/123      → User Service
GET /api/orders/456     → Order Service
POST /api/payments      → Payment Service
GET /api/notifications  → Notification Service

X-API-Version: v1  → Legacy Service
X-API-Version: v2  → New Service

GET  /api/products  → Product Read Service (optimized for queries)
POST /api/products  → Product Write Service (optimized for writes)

GET /api/search?type=products  → Product Search Service
GET /api/search?type=users     → User Search Service

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1710000000
Retry-After: 30
 
{
  "error": "rate_limit_exceeded",
  "message": "You have exceeded 100 requests per minute",
  "retry_after": 30
}

Client sends:
POST /api/v2/users
Content-Type: application/json
{ "firstName": "John", "lastName": "Doe" }
 
Gateway transforms to:
POST /users
Content-Type: application/json
X-API-Version: 2
{ "first_name": "John", "last_name": "Doe" }

Backend responds:
{ "user_id": 123, "first_name": "John", "created_at": "2026-03-11T..." }
 
Gateway transforms to:
{ "id": 123, "firstName": "John", "createdAt": "2026-03-11T..." }

{
  "user": {
    "id": 123,
    "name": "John Doe",
    "email": "john@example.com"
  },
  "recentOrders": [
    { "id": 456, "total": 99.99, "status": "delivered" },
    { "id": 457, "total": 49.99, "status": "processing" }
  ],
  "paymentMethods": [
    { "type": "credit_card", "last4": "4242" }
  ]
}

circuit_breaker:
  threshold: 5          # Open after 5 consecutive failures
  timeout: 30s          # Wait 30s before trying half-open
  half_open_requests: 3 # Allow 3 test requests in half-open
  failure_codes:        # Which HTTP codes count as failures
    - 500
    - 502
    - 503
    - 504

GET /api/v1/users/123  → User Service v1
GET /api/v2/users/123  → User Service v2

GET /api/users/123
Accept: application/vnd.api.v2+json  → User Service v2

GET /api/users/123?version=2  → User Service v2

routes:
  - path: /api/v1/users
    service: user-service-v1
    strip_prefix: /api/v1
 
  - path: /api/v2/users
    service: user-service-v2
    strip_prefix: /api/v2
 
  # Default latest version
  - path: /api/users
    service: user-service-v2
    strip_prefix: /api

routes:
  - path: /api/v1/users
    service: user-service
    transform:
      request:
        rename_fields:
          firstName: first_name
          lastName: last_name
      response:
        rename_fields:
          first_name: firstName
          last_name: lastName

# docker-compose.yml
version: "3.8"
 
services:
  kong-database:
    image: postgres:15-alpine
    environment:
      POSTGRES_USER: kong
      POSTGRES_DB: kong
      POSTGRES_PASSWORD: kongpass
    volumes:
      - kong-data:/var/lib/postgresql/data
 
  kong-migration:
    image: kong:3.6
    depends_on:
      - kong-database
    environment:
      KONG_DATABASE: postgres
      KONG_PG_HOST: kong-database
      KONG_PG_PASSWORD: kongpass
    command: kong migrations bootstrap
 
  kong:
    image: kong:3.6
    depends_on:
      - kong-database
      - kong-migration
    environment:
      KONG_DATABASE: postgres
      KONG_PG_HOST: kong-database
      KONG_PG_PASSWORD: kongpass
      KONG_PROXY_ACCESS_LOG: /dev/stdout
      KONG_ADMIN_ACCESS_LOG: /dev/stdout
      KONG_PROXY_ERROR_LOG: /dev/stderr
      KONG_ADMIN_ERROR_LOG: /dev/stderr
      KONG_ADMIN_LISTEN: "0.0.0.0:8001"
    ports:
      - "8000:8000"    # Proxy port
      - "8443:8443"    # Proxy SSL port
      - "8001:8001"    # Admin API
 
volumes:
  kong-data:

# Create a service
curl -i -X POST http://localhost:8001/services/ \
  --data "name=user-service" \
  --data "url=http://user-service:3000"
 
# Create a route for the service
curl -i -X POST http://localhost:8001/services/user-service/routes \
  --data "name=user-routes" \
  --data "paths[]=/api/users" \
  --data "strip_path=true"
 
# Create another service
curl -i -X POST http://localhost:8001/services/ \
  --data "name=order-service" \
  --data "url=http://order-service:3001"
 
# Route for order service
curl -i -X POST http://localhost:8001/services/order-service/routes \
  --data "name=order-routes" \
  --data "paths[]=/api/orders" \
  --data "strip_path=true"

# Rate limiting — 100 requests per minute per consumer
curl -i -X POST http://localhost:8001/services/user-service/plugins \
  --data "name=rate-limiting" \
  --data "config.minute=100" \
  --data "config.policy=local"
 
# JWT authentication
curl -i -X POST http://localhost:8001/services/user-service/plugins \
  --data "name=jwt"
 
# Request logging
curl -i -X POST http://localhost:8001/services/user-service/plugins \
  --data "name=file-log" \
  --data "config.path=/tmp/api-logs.log"
 
# CORS
curl -i -X POST http://localhost:8001/services/user-service/plugins \
  --data "name=cors" \
  --data "config.origins[]=https://example.com" \
  --data "config.methods[]=GET" \
  --data "config.methods[]=POST" \
  --data "config.headers[]=Authorization" \
  --data "config.headers[]=Content-Type"
 
# Response transformer — remove internal headers
curl -i -X POST http://localhost:8001/services/user-service/plugins \
  --data "name=response-transformer" \
  --data "config.remove.headers=X-Powered-By" \
  --data "config.remove.headers=Server"

# kong.yml
_format_version: "3.0"
 
services:
  - name: user-service
    url: http://user-service:3000
    routes:
      - name: user-routes
        paths:
          - /api/users
        strip_path: true
    plugins:
      - name: rate-limiting
        config:
          minute: 100
          policy: redis
          redis_host: redis
      - name: jwt
      - name: cors
        config:
          origins:
            - "https://example.com"
          methods:
            - GET
            - POST
            - PUT
            - DELETE
 
  - name: order-service
    url: http://order-service:3001
    routes:
      - name: order-routes
        paths:
          - /api/orders
        strip_path: true
    plugins:
      - name: rate-limiting
        config:
          minute: 50
          policy: redis
          redis_host: redis
 
consumers:
  - username: mobile-app
    jwt_secrets:
      - key: mobile-app-key
        algorithm: HS256
        secret: your-secret-key
 
  - username: web-app
    jwt_secrets:
      - key: web-app-key
        algorithm: HS256
        secret: your-other-secret

# serverless.yml (Serverless Framework)
service: my-api
 
provider:
  name: aws
  runtime: nodejs20.x
  region: us-east-1
 
functions:
  getUsers:
    handler: handlers/users.getAll
    events:
      - http:
          path: /users
          method: get
          cors: true
          authorizer:
            type: COGNITO_USER_POOLS
            authorizerId:
              Ref: ApiGatewayAuthorizer
 
  getUser:
    handler: handlers/users.getById
    events:
      - http:
          path: /users/{id}
          method: get
          cors: true
 
  createOrder:
    handler: handlers/orders.create
    events:
      - http:
          path: /orders
          method: post
          cors: true
 
resources:
  Resources:
    # Usage plan with rate limiting
    ApiUsagePlan:
      Type: AWS::ApiGateway::UsagePlan
      Properties:
        UsagePlanName: BasicPlan
        Throttle:
          BurstLimit: 100
          RateLimit: 50
        Quota:
          Limit: 10000
          Period: MONTH
 
    # API Key
    ApiKey:
      Type: AWS::ApiGateway::ApiKey
      Properties:
        Name: mobile-app-key
        Enabled: true
 
    # Cognito authorizer
    ApiGatewayAuthorizer:
      Type: AWS::ApiGateway::Authorizer
      Properties:
        Name: CognitoAuthorizer
        Type: COGNITO_USER_POOLS
        ProviderARNs:
          - !GetAtt UserPool.Arn
        RestApiId:
          Ref: ApiGatewayRestApi
        IdentitySource: method.request.header.Authorization

# AWS SAM template
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
 
Resources:
  HttpApi:
    Type: AWS::Serverless::HttpApi
    Properties:
      StageName: prod
      CorsConfiguration:
        AllowMethods:
          - GET
          - POST
          - PUT
          - DELETE
        AllowOrigins:
          - "https://example.com"
        AllowHeaders:
          - Authorization
          - Content-Type
 
  GetUsersFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: handlers/users.getAll
      Runtime: nodejs20.x
      Events:
        GetUsers:
          Type: HttpApi
          Properties:
            ApiId: !Ref HttpApi
            Path: /users
            Method: GET

<!-- pom.xml -->
<dependencies>
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-gateway</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-actuator</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-circuitbreaker-resilience4j</artifactId>
    </dependency>
</dependencies>

# application.yml
spring:
  cloud:
    gateway:
      routes:
        # User service
        - id: user-service
          uri: http://user-service:3000
          predicates:
            - Path=/api/users/**
          filters:
            - StripPrefix=1
            - name: CircuitBreaker
              args:
                name: userServiceCB
                fallbackUri: forward:/fallback/users
            - name: RequestRateLimiter
              args:
                redis-rate-limiter.replenishRate: 10
                redis-rate-limiter.burstCapacity: 20
                key-resolver: "#{@apiKeyResolver}"
            - AddRequestHeader=X-Gateway, spring-cloud
 
        # Order service
        - id: order-service
          uri: http://order-service:3001
          predicates:
            - Path=/api/orders/**
            - Method=GET,POST,PUT
          filters:
            - StripPrefix=1
            - name: Retry
              args:
                retries: 3
                statuses: BAD_GATEWAY,SERVICE_UNAVAILABLE
                methods: GET
                backoff:
                  firstBackoff: 100ms
                  maxBackoff: 500ms
                  factor: 2
 
        # Version-based routing
        - id: user-service-v2
          uri: http://user-service-v2:3000
          predicates:
            - Path=/api/users/**
            - Header=X-API-Version, v2
          filters:
            - StripPrefix=1
 
      # Default filters applied to all routes
      default-filters:
        - name: RequestSize
          args:
            maxSize: 5MB
        - DedupeResponseHeader=Access-Control-Allow-Origin
 
      # Global CORS
      globalcors:
        corsConfigurations:
          "[/**]":
            allowedOrigins: "https://example.com"
            allowedMethods: "*"
            allowedHeaders: "*"

@Component
public class JwtAuthFilter implements GatewayFilterFactory<JwtAuthFilter.Config> {
 
    @Override
    public GatewayFilter apply(Config config) {
        return (exchange, chain) -> {
            String token = exchange.getRequest().getHeaders()
                .getFirst(HttpHeaders.AUTHORIZATION);
 
            if (token == null || !token.startsWith("Bearer ")) {
                exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED);
                return exchange.getResponse().setComplete();
            }
 
            try {
                Claims claims = validateToken(token.substring(7));
 
                // Add user info as headers for downstream services
                ServerHttpRequest modifiedRequest = exchange.getRequest()
                    .mutate()
                    .header("X-User-ID", claims.getSubject())
                    .header("X-User-Role", claims.get("role", String.class))
                    .build();
 
                return chain.filter(
                    exchange.mutate().request(modifiedRequest).build()
                );
            } catch (Exception e) {
                exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED);
                return exchange.getResponse().setComplete();
            }
        };
    }
 
    public static class Config {
        // Configuration properties
    }
}

@Configuration
public class RateLimiterConfig {
 
    @Bean
    public KeyResolver apiKeyResolver() {
        return exchange -> {
            String apiKey = exchange.getRequest().getHeaders()
                .getFirst("X-API-Key");
            return Mono.just(apiKey != null ? apiKey : exchange.getRequest()
                .getRemoteAddress().getAddress().getHostAddress());
        };
    }
 
    @Bean
    public KeyResolver userKeyResolver() {
        return exchange -> {
            String userId = exchange.getRequest().getHeaders()
                .getFirst("X-User-ID");
            return Mono.just(userId != null ? userId : "anonymous");
        };
    }
}

{
  "timestamp": "2026-03-11T10:30:00Z",
  "request_id": "req-abc-123",
  "method": "GET",
  "path": "/api/users/123",
  "status": 200,
  "latency_ms": 45,
  "client_ip": "203.0.113.50",
  "api_key": "mobile-app",
  "user_id": "user-456",
  "upstream_service": "user-service",
  "upstream_latency_ms": 38,
  "cache_status": "MISS",
  "rate_limit_remaining": 95
}