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
    - host

hosts:
  - id: "host-001"
    name: "localhost"
    domain: "localhost:8080"

targets:
  - id: "target-001"
    name: "httpbin"
    url: "https://httpbin.org"

apis:
  - id: "api-001"
    host: "host-001"
    target: "target-001"

routes:
  - id: "route-001"
    api: "api-001"
    path: "/api/v1/*"
    strip_prefix:
      enabled: true
      prefix: "/api/v1"

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 with structured JSON
host	Logs the host header for each request

Hosts

Virtual hosting configuration for domain-based routing.

Field	Type	Description
id	string	Unique host identifier (referenced by APIs)
name	string	Human-readable name
domain	string	Domain/host name to match

Targets

Backend service definitions referenced by APIs.

Field	Type	Description
id	string	Unique target identifier (referenced by APIs)
name	string	Human-readable name
url	string	Backend URL to proxy to

APIs

Links hosts to backend targets.

Field	Type	Description
id	string	Unique API identifier (referenced by routes)
host	string	Host ID to use
target	string	Target ID to proxy to

Routes

Route definitions with path patterns and prefix stripping.

Field	Type	Description
id	string	Unique route identifier
api	string	API ID to use for this route
path	string	Chi route pattern (e.g., /api/v1/*)
strip_prefix	object	Prefix stripping configuration

Strip Prefix

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

Example Configurations

Simple Proxy (No Prefix Stripping)

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

hosts:
  - id: "host-001"
    name: "localhost"
    domain: "localhost:8080"

targets:
  - id: "target-001"
    name: "backend"
    url: "https://api.example.com"

apis:
  - id: "api-001"
    host: "host-001"
    target: "target-001"

routes:
  - id: "route-001"
    api: "api-001"
    path: "/api/*"

Request flow:

• Client requests: /api/users/123
• Backend receives: /api/users/123

Prefix Stripping

routes:
  - id: "route-001"
    api: "api-001"
    path: "/api/v1/*"
    strip_prefix:
      enabled: true
      prefix: "/api/v1"

Request flow:

• Client requests: /api/v1/users/123
• Gateway strips: /api/v1
• Backend receives: /users/123

Multiple Routes

routes:
  - id: "public-route"
    api: "api-001"
    path: "/public/*"
    strip_prefix:
      enabled: true
      prefix: "/public"

  - id: "api-route"
    api: "api-001"
    path: "/api/v1/*"
    strip_prefix:
      enabled: true
      prefix: "/api/v1"

Multiple Backends

hosts:
  - id: "host-001"
    name: "api-host"
    domain: "api.example.com"
  - id: "host-002"
    name: "admin-host"
    domain: "admin.example.com"

targets:
  - id: "target-001"
    name: "api-backend"
    url: "https://api-backend.internal"
  - id: "target-002"
    name: "admin-backend"
    url: "https://admin-backend.internal"

apis:
  - id: "api-001"
    host: "host-001"
    target: "target-001"
  - id: "api-002"
    host: "host-002"
    target: "target-002"

routes:
  - id: "route-001"
    api: "api-001"
    path: "/api/*"
  - id: "route-002"
    api: "api-002"
    path: "/admin/*"

Configuration Loading

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

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

For Docker deployments, mount the config file:

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

Chi Route Patterns

The gateway uses chi/v5 routing patterns. Common patterns:

Pattern	Matches	Example
/api/*	/api/ and any subpath	/api/users, /api/users/123
/api/v1/*	/api/v1/ and any subpath	/api/v1/users
/users/{id}	/users/ with any value	/users/123
/files/*	/files/ and any subpath	/files/doc.pdf

Note: /* matches zero or more path segments.