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/dev/*
curl http://localhost:8080/api/v1/dev/users

# With API key authentication
curl -H "X-Api-Key: your-key-here" http://localhost:8080/api/v1/dev/data

# With session authentication
curl -H "Authorization: Bearer token" http://localhost:8080/api/v1/protected

Route Examples

Strip Prefix Example

Configuration:

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

Authentication Example

Configuration:

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

Valid request:

curl -H "X-Api-Key: secret123" http://localhost:8080/api/v1/data

Invalid request (missing header):

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

WAF Method Filtering Example

Configuration:

security:
  waf:
    enabled: true
    methods: ["GET", "POST"]

Allowed:

curl -X GET http://localhost:8080/api/v1/data
curl -X POST http://localhost:8080/api/v1/data

Blocked:

curl -X DELETE http://localhost:8080/api/v1/data
# Returns: 403 Forbidden

Logging

The gateway uses structured logging via masterlog. Logs include:

• Request ID (if enabled)
• Client IP (if real_ip enabled)
• Request method and path
• Response status

Example log output:

{
  "level": "info",
  "msg": "Registering route",
  "path": "/api/v1/dev/*"
}

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

3. Check logs for detailed error messages

401 Unauthorized

• Verify auth header is included
• Check header name matches configuration
• Verify path is not excluded from auth

403 Forbidden

• Check WAF method configuration
• Verify HTTP method is allowed

Backend connection errors

• Verify API target URL is correct
• Check backend service is running
• Verify network connectivity

Performance Considerations

• The gateway uses Go's httputil.ReverseProxy for efficient proxying
• Keep-alive connections are reused by default
• Consider connection pooling for high-traffic scenarios
• Monitor memory usage with high request volumes