API Gateway Proxy Documentation

Overview

An API gateway proxy serves as a single entry point for all client requests, routing them to appropriate backend services while providing essential cross-cutting concerns like authentication, rate limiting, request transformation, and monitoring. This documentation provides comprehensive guidance for implementing production-ready API gateway proxies.

The gateway acts as a reverse proxy that sits between clients and your backend services, abstracting the complexity of your microservices architecture. It handles request routing, protocol translation, and centralized policy enforcement, allowing your backend services to focus on business logic.

Installation

System Requirements

Before installation, ensure your system meets the following minimum requirements:

Docker Installation

The recommended method for deploying the API gateway is using Docker containers. This approach ensures consistency across environments and simplifies dependency management.

# Pull the latest image
docker pull api-gateway-proxy:latest

# Run the gateway container
docker run -d \
  --name api-gateway \
  -p 8080:8080 \
  -p 8443:8443 \
  -v $(pwd)/config:/etc/gateway/config \
  -v $(pwd)/logs:/var/log/gateway \
  api-gateway-proxy:latest

Binary Installation

For bare-metal deployments, download the platform-specific binary and install it manually:

# Download the binary
wget https://releases.api-gateway.io/v3.2.1/gateway-linux-amd64.tar.gz

# Extract and install
tar -xzf gateway-linux-amd64.tar.gz
sudo mv gateway /usr/local/bin/
sudo chmod +x /usr/local/bin/gateway

# Verify installation
gateway version

Configuration

Configuration File Structure

The gateway uses a YAML-based configuration file that defines routes, services, policies, and global settings. The configuration file is typically located at /etc/gateway/config.yaml.

# Global settings
server:
  http_port: 8080
  https_port: 8443
  admin_port: 9090
  
logging:
  level: info
  format: json
  output: /var/log/gateway/access.log
  
# Service definitions
services:
  - name: user-service
    url: http://user-service:3001
    health_check:
      interval: 30s
      timeout: 5s
      
# Route definitions
routes:
  - path: /api/users/*
    service: user-service
    strip_prefix: false
    rate_limit: 1000/minute

Environment Variables

Configuration values can be overridden using environment variables. This is particularly useful for containerized deployments where secrets and environment-specific values should not be stored in configuration files.

# Override HTTP port
GATEWAY_HTTP_PORT=8080

# Set logging level
GATEWAY_LOG_LEVEL=debug

# Database connection string
GATEWAY_DB_CONNECTION=postgresql://user:pass@db:5432/gateway

# Enable metrics export
GATEWAY_METRICS_ENABLED=true

Authentication

JWT Authentication

JSON Web Token (JWT) authentication is the most common method for securing API gateway routes. The gateway validates incoming tokens against configured public keys before routing requests to backend services.

authentication:
  jwt:
    enabled: true
    issuer: https://auth.example.com
    audience: api-gateway
    algorithms: [RS256]
    public_key: |
      -----BEGIN PUBLIC KEY-----
      MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
      -----END PUBLIC KEY-----

API Key Authentication

For simpler authentication scenarios or service-to-service communication, API keys provide a straightforward alternative. Keys can be passed via headers or query parameters.

authentication:
  api_key:
    enabled: true
    header: X-API-Key
    query_param: api_key
    keys:
      - name: service-account
        key: sk_live_abc123xyz
        rate_limit: 10000/hour
      - name: external-partner
        key: sk_live_def456uvw
        rate_limit: 5000/hour

Rate Limiting

Rate limiting protects your backend services from being overwhelmed by controlling the number of requests clients can make within a time window. The gateway supports multiple rate limiting strategies:

Token Bucket Algorithm

The token bucket algorithm allows burst traffic up to a defined limit while maintaining an average rate over time. This is ideal for APIs that experience variable load patterns.

rate_limiting:
  algorithm: token_bucket
  default:
    requests: 1000
    window: 1m
    burst_size: 100
    
  per_endpoint:
    - path: /api/search
      requests: 100
      window: 1m
    - path: /api/upload
      requests: 10
      window: 1m

Sliding Window Algorithm

The sliding window algorithm provides smoother rate limiting by calculating the rate over a continuously moving time window, preventing boundary issues common with fixed windows.

Monitoring and Observability

Metrics Collection

The gateway exposes Prometheus-compatible metrics on the admin port, providing real-time visibility into request rates, latency distributions, error rates, and resource utilization.

Health Checks

The gateway provides multiple health check endpoints for integration with load balancers and orchestration platforms:

# Liveness probe - checks if the gateway process is running
GET /health/live
Response: 200 OK

# Readiness probe - checks if the gateway can handle requests
GET /health/ready
Response: 200 OK or 503 Service Unavailable

# Detailed health check with dependency status
GET /health/detail
Response: {
  "status": "healthy",
  "checks": {
    "database": "ok",
    "cache": "ok",
    "upstream_services": "ok"
  }
}

Security Best Practices

Transport Layer Security

Always enable TLS for production deployments. The gateway supports automatic certificate management via Let's Encrypt or manual certificate configuration.

tls:
  enabled: true
  cert_file: /etc/gateway/certs/server.crt
  key_file: /etc/gateway/certs/server.key
  min_version: TLS1.2
  cipher_suites:
    - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
    - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

Request Size Limits

Configure maximum request body sizes to prevent denial-of-service attacks and resource exhaustion:

security:
  max_request_body_size: 10MB
  max_header_size: 1MB
  request_timeout: 30s

API Reference

Admin API Endpoints

The gateway exposes administrative endpoints on a separate port for configuration management and monitoring:

List All Routes

GET /admin/routes
Authorization: Bearer <admin-token>

Response 200:
{
  "routes": [
    {
      "id": "route-001",
      "path": "/api/users/*",
      "service": "user-service",
      "enabled": true
    }
  ]
}

Create New Route

POST /admin/routes
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "path": "/api/orders/*",
  "service": "order-service",
  "strip_prefix": false,
  "rate_limit": "500/minute"
}

Response 201:
{
  "id": "route-002",
  "status": "created"
}

Update Route

PUT /admin/routes/{route_id}
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "rate_limit": "1000/minute"
}

Response 200:
{
  "id": "route-002",
  "status": "updated"
}

Delete Route

DELETE /admin/routes/{route_id}
Authorization: Bearer <admin-token>

Response 204 No Content