api-gateway/.docs/usage.md

# Usage

## Running the Gateway

### Local Development

```bash
cd app
go run main.go
```

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

### Docker

```bash
# 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

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

## Health Check

Check if the gateway is running:

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

Response: `OK`

## Making Requests

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

```bash
# 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:**
```yaml
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:**
```yaml
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:**
```bash
# 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:**
```json
{
  "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:
```bash
lsof -i :8080
```

2. Verify configuration file exists and is valid YAML:
```bash
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

```yaml
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

```yaml
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

```yaml
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.