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"
    security:
      auth:
        enabled: true
        type: "api_key"
        header: "X-Api-Key"
        path:
          include: []
          exclude: []

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, prefix stripping, and authentication.

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
security	object	Security policies (auth)

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 identifier (for documentation)
header	string	Header name to validate (e.g., X-Api-Key, Authorization)
path	object	Path-based filtering configuration

Auth Path Filtering

Field	Type	Description
include	array	Paths that require auth (empty = all, if set only these)
exclude	array	Paths that skip auth (only used if include is empty)

Path Filtering Logic:

Include	Exclude	Behavior
Empty	Empty	Auth required for ALL paths
Set	Empty	Auth required ONLY for paths matching include
Empty	Set	Auth required for ALL EXCEPT paths matching exclude
Set	Set	Include takes precedence (same as "Set, Empty")

Wildcards in Path Patterns:

• * matches any path
• /api/* matches /api/ and any subpath
• /api/v1/public/test/* matches the prefix and any subpath

Example Configurations

Public API (No Auth)

routes:
  - id: "public-api"
    api: "api-001"
    path: "/public/*"
    strip_prefix:
      enabled: true
      prefix: "/public"
    security:
      auth:
        enabled: false

Protected API (All Paths Require Auth)

routes:
  - id: "protected-api"
    api: "api-001"
    path: "/api/v1/*"
    strip_prefix:
      enabled: true
      prefix: "/api/v1"
    security:
      auth:
        enabled: true
        header: "X-Api-Key"
        path:
          include: []
          exclude: []

Public with Protected Sub-paths (Include)

routes:
  - id: "mixed-api"
    api: "api-001"
    path: "/api/*"
    strip_prefix:
      enabled: true
      prefix: "/api"
    security:
      auth:
        enabled: true
        header: "X-Api-Key"
        path:
          include: ["/api/admin/*", "/api/users/*/profile"]
          exclude: []

In this example:

• /api/admin/users → Requires auth (matches include)
• /api/users/123/profile → Requires auth (matches include)
• /api/public/data → No auth (doesn't match include)
• /api/health → No auth (doesn't match include)

Protected with Public Sub-paths (Exclude)

routes:
  - id: "protected-with-public"
    api: "api-001"
    path: "/api/*"
    security:
      auth:
        enabled: true
        header: "Authorization"
        path:
          include: []
          exclude: ["/api/health", "/api/public/*", "/api/v1/public/test/*"]

In this example:

• /api/health → No auth (matches exclude)
• /api/public/data → No auth (matches exclude)
• /api/v1/public/test/123 → No auth (matches exclude)
• /api/users → Requires auth (doesn't match exclude)
• /api/admin/settings → Requires auth (doesn't match exclude)

Multiple Routes with Different Auth

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

  - id: "user-route"
    api: "api-001"
    path: "/users/*"
    strip_prefix:
      enabled: true
      prefix: "/users"
    security:
      auth:
        enabled: true
        header: "X-Api-Key"
        path:
          include: []
          exclude: ["/users/login", "/users/register"]

  - id: "admin-route"
    api: "api-001"
    path: "/admin/*"
    strip_prefix:
      enabled: true
      prefix: "/admin"
    security:
      auth:
        enabled: true
        header: "Authorization"
        path:
          include: []
          exclude: []

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.

Debug Logging

To see detailed authentication decisions, enable DEBUG logging in main.go:

masterlog.SetLevel(masterlog.LevelDebug)

This will output logs like:

{
  "level": "debug",
  "msg": "AuthMiddleware: Checking if path requires auth",
  "path": "/api/v1/users",
  "requires_auth": true,
  "include": [],
  "exclude": ["/api/v1/public/*"]
}