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

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"

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

Requests:

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

# API route - backend receives /users
curl 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"
}

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

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

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

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

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

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"

  - id: "orders-route"
    api: "order-api"
    path: "/orders/*"
    strip_prefix:
      enabled: true
      prefix: "/orders"

External API Proxy

targets:
  - id: "external-api"
    name: "External API"
    url: "https://api.external.com"

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

routes:
  - id: "external-proxy"
    api: "external"
    path: "/proxy/external/*"
    strip_prefix:
      enabled: true
      prefix: "/proxy/external"

Request to /proxy/external/users becomes /users on the external API.