api-gateway/.docs/configuration.md

Configuration

The gateway is configured via a single YAML file (gateway.yaml). This document describes all available configuration options.

Configuration File Structure

gateway:
  host: "0.0.0.0"
  port: 8080
  features:
    - request_id
    - real_ip
    - logger

proxies:
  - id: "proxy-id"
    host: "example.com"
    target: "http://backend:3000"

apis:
  - id: "api-id"
    target: "https://api.example.com"

routes:
  - id: "route-id"
    path: "/api/v1/*"
    strip_prefix:
      enabled: true
      prefix: "/api/v1"
    security:
      auth:
        enabled: true
        type: "api_key"
        header: "X-Api-Key"
        path:
          include: []
          exclude: []
      waf:
        enabled: true
        methods: ["GET", "POST"]

Sections

Gateway

Global gateway configuration.

Field	Type	Description	Default
host	string	Host address to bind to	Required
port	integer	Port number	Required
features	array	Global middleware features	Required

Features

Available global features:

Feature	Description
request_id	Adds unique request ID to each request
real_ip	Determines real client IP from headers
logger	Logs all HTTP requests

Proxies

Virtual hosting configuration for host-based routing.

Field	Type	Description
id	string	Unique proxy identifier
host	string	Domain/host name to match
target	string	Backend URL to proxy to

APIs

Backend service definitions referenced by routes.

Field	Type	Description
id	string	Unique API identifier (referenced by routes)
target	string	Backend URL

Routes

Route definitions with security policies.

Field	Type	Description
id	string	Unique route identifier (must match API ID)
path	string	Chi route pattern (e.g., /api/v1/*)
strip_prefix	object	Prefix stripping configuration
security	object	Security policies (auth, WAF)

Strip Prefix

Field	Type	Description
enabled	boolean	Enable prefix stripping
prefix	string	Prefix to remove from path

Security

Authentication

Field	Type	Description
enabled	boolean	Enable authentication
type	string	Auth type (api_key, session, etc.)
header	string	Header name to validate
path	object	Path-based filtering

Auth Path Filtering

Field	Type	Description
include	array	Paths that require auth (empty = all)
exclude	array	Paths that skip auth

Include/Exclude Logic:

• If include is set → only matching paths require auth
• If include is empty → all paths require auth except exclude

Wildcards (*) are supported in path patterns.

WAF (Web Application Firewall)

Field	Type	Description
enabled	boolean	Enable WAF
methods	array	Allowed HTTP methods (["*"] for all)

Example Configurations

Public API (No Auth)

routes:
  - id: "public-api"
    path: "/public/*"
    strip_prefix:
      enabled: true
      prefix: "/public"
    security:
      auth:
        enabled: false
      waf:
        enabled: true
        methods: ["GET", "POST"]

Protected API with API Key

routes:
  - id: "protected-api"
    path: "/api/v1/*"
    strip_prefix:
      enabled: true
      prefix: "/api/v1"
    security:
      auth:
        enabled: true
        type: "api_key"
        header: "X-Api-Key"
      waf:
        enabled: true
        methods: ["*"]

Mixed Auth (Path-based)

routes:
  - id: "mixed-api"
    path: "/api/*"
    security:
      auth:
        enabled: true
        header: "Authorization"
        path:
          include: ["/api/admin/*", "/api/users/*/profile"]
          exclude: ["/api/health", "/api/public/*"]
      waf:
        enabled: true
        methods: ["*"]

Configuration Loading

The gateway loads configuration from a file path relative to the binary:

cfg, err := config.NewFileConfig("../gateway.yaml")

For Docker deployments, mount the config file:

volumes:
  - ./gateway.yaml:/app/gateway.yaml:ro