api-gateway/.docs/usage.md

Usage

Running the Gateway

Local Development

cd app
go run main.go

The gateway will start on the configured host and port (default: 0.0.0.0:8080).

Docker

# Pull and run (builds locally if image not available)
docker compose up -d

# View logs
docker compose logs -f gateway

# Stop
docker compose down

Build from Source

cd app
go build -o gateway main.go
./gateway

Health Check

Check if the gateway is running:

curl http://localhost:8080/_/health

Response: OK

Making Requests

After configuring routes in gateway.yaml, make requests to the gateway:

# Example: Request to a route configured at /api/v1/*
curl http://localhost:8080/api/v1/users

# All HTTP methods are supported
curl -X POST http://localhost:8080/api/v1/data
curl -X PUT http://localhost:8080/api/v1/data/123
curl -X DELETE http://localhost:8080/api/v1/data/123

Authentication

Using API Key Authentication

Configuration:

security:
  auth:
    enabled: true
    header: "X-Api-Key"

Valid request:

curl -H "X-Api-Key: your-secret-key" http://localhost:8080/api/v1/data

Invalid request (missing header):

curl http://localhost:8080/api/v1/data
# Returns: 401 Unauthorized

Using Bearer Token Authentication

Configuration:

security:
  auth:
    enabled: true
    header: "Authorization"

Valid request:

curl -H "Authorization: Bearer your-token-here" http://localhost:8080/api/v1/data

Path-Based Authentication Examples

All Paths Require Auth

Configuration:

security:
  auth:
    enabled: true
    header: "X-Api-Key"
    path:
      include: []
      exclude: []

All requests to this route require authentication.

Only Specific Paths Require Auth (Include)

Configuration:

security:
  auth:
    enabled: true
    header: "X-Api-Key"
    path:
      include: ["/api/admin/*", "/api/users/*/profile"]
      exclude: []

Request examples:

# Requires auth (matches include)
curl -H "X-Api-Key: key" http://localhost:8080/api/admin/users
curl -H "X-Api-Key: key" http://localhost:8080/api/users/123/profile

# No auth required (doesn't match include)
curl http://localhost:8080/api/public/data
curl http://localhost:8080/api/health

All Paths Except Specific Ones Require Auth (Exclude)

Configuration:

security:
  auth:
    enabled: true
    header: "X-Api-Key"
    path:
      include: []
      exclude: ["/api/health", "/api/public/*"]

Request examples:

# No auth required (matches exclude)
curl http://localhost:8080/api/health
curl http://localhost:8080/api/public/data

# Requires auth (doesn't match exclude)
curl -H "X-Api-Key: key" http://localhost:8080/api/users
curl -H "X-Api-Key: key" http://localhost:8080/api/admin/settings

Route Examples

Strip Prefix Example

Configuration:

routes:
  - id: "api"
    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 Example

Configuration:

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

  - id: "api-route"
    api: "api-001"
    path: "/api/v1/*"
    strip_prefix:
      enabled: true
      prefix: "/api/v1"
    security:
      auth:
        enabled: true
        header: "X-Api-Key"

Requests:

# Public route - no auth, backend receives /status
curl http://localhost:8080/public/status

# API route - requires auth, backend receives /users
curl -H "X-Api-Key: key" http://localhost:8080/api/v1/users

Logging

The gateway uses structured JSON logging via masterlog. All HTTP requests are logged with:

• Request ID (if enabled)
• Client IP (if real_ip enabled)
• Request method and path
• Response status code
• Request duration
• Host header

Example log output:

{
  "level": "info",
  "msg": "HTTP Request",
  "method": "GET",
  "path": "/api/v1/users",
  "status": 200,
  "duration": "45ms",
  "host": "localhost:8080",
  "ip": "127.0.0.1:52342"
}

Debug Logging

To enable detailed authentication logging, set DEBUG level in main.go:

masterlog.SetLevel(masterlog.LevelDebug)

This will output detailed auth decision logs:

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

Troubleshooting

Gateway fails to start

1. Check if port is already in use:

lsof -i :8080

2. Verify configuration file exists and is valid YAML:

cat ../gateway.yaml

3. Check logs for detailed error messages

401 Unauthorized

• Verify auth header is included
• Check header name matches configuration (case-sensitive)
• Verify path is not excluded from auth (check exclude patterns)
• Enable DEBUG logging to see auth decision process

404 Not Found

• Verify the route path matches your request
• Check chi route pattern syntax (use /* for wildcards)
• Ensure the route is registered (check startup logs)

Backend connection errors

• Verify target URL is correct in configuration
• Check backend service is running and accessible
• Verify network connectivity from gateway to backend
• Check DNS resolution if using domain names

Route not matching

• Ensure request path matches the route pattern exactly
• Remember that /* matches zero or more path segments
• Check that multiple routes don't have conflicting patterns

Auth not working as expected

1. Enable DEBUG logging to see auth decisions:

masterlog.SetLevel(masterlog.LevelDebug)

2. Check the logs for:

   • Whether the path requires auth
   • Whether the auth header is present
   • Which patterns are being matched

3. Verify your include/exclude patterns:

   • Wildcards end with *
   • Patterns are prefix-based (e.g., /api/v1/public/test/*)

Performance Considerations

• The gateway uses Go's httputil.ReverseProxy for efficient proxying
• HTTP/2 is supported when both client and backend support it
• Keep-alive connections are reused by default
• Consider connection pooling for high-traffic scenarios
• Monitor memory usage with high request volumes

Common Patterns

API Versioning with Auth

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

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

Mixed Authentication

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

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

Microservices Routing

targets:
  - id: "user-service"
    name: "User Service"
    url: "https://user-service.internal"
  - id: "order-service"
    name: "Order Service"
    url: "https://order-service.internal"

apis:
  - id: "user-api"
    host: "host-001"
    target: "user-service"
  - id: "order-api"
    host: "host-001"
    target: "order-service"

routes:
  - id: "users-route"
    api: "user-api"
    path: "/users/*"
    strip_prefix:
      enabled: true
      prefix: "/users"
    security:
      auth:
        enabled: true
        header: "X-Api-Key"

  - id: "orders-route"
    api: "order-api"
    path: "/orders/*"
    strip_prefix:
      enabled: true
      prefix: "/orders"
    security:
      auth:
        enabled: true
        header: "Authorization"