docs/API_GATEWAY.md

API Gateway for RAG Agent Framework

A production-ready, multi-protocol API Gateway for the AmaniQuery RAG Agent Framework. Provides unified access for frontend clients with comprehensive security, observability, and performance features.

Architecture

graph TB
    subgraph "Client Layer"
        WEB[Web Browser]
        MOBILE[Mobile App]
        DEVELOPER[Developer Portal]
    end
    
    subgraph "API Gateway Layer"
        GW[API Gateway<br/>Go Service]
        
        subgraph "Middleware Stack"
            CORS[CORS Handler]
            RATE[Rate Limiter]
            AUTH[JWT Validator]
            AUDIT[Audit Logger]
        end
        
        subgraph "Protocol Handlers"
            REST[REST Handler]
            WS[WebSocket Handler]
            GQL[GraphQL Handler]
        end
    end
    
    subgraph "Backend Services"
        AGENT[Agent Service]
        RETRIEVER[Retriever Service]
        GENERATOR[Generator Service]
        MEMORY[Memory Service]
    end
    
    WEB --> GW
    MOBILE --> GW
    DEVELOPER --> GW
    
    GW --> CORS --> RATE --> AUTH --> AUDIT
    AUDIT --> REST
    AUDIT --> WS
    AUDIT --> GQL
    
    REST --> AGENT
    WS --> AGENT
    GQL --> AGENT

Features

Multi-Protocol Support

• REST API - Standard HTTP endpoints for queries, agents, memory
• WebSocket - Real-time streaming for query responses
• Server-Sent Events - Lightweight streaming alternative
• GraphQL - Flexible query interface (placeholder)

Security

• JWT Authentication - Token-based auth with HMAC/RSA signing
• OPA Authorization - Fine-grained policy-based access control
• Rate Limiting - Token bucket with per-tenant/user isolation
• CORS - Configurable cross-origin policies
• Security Headers - HSTS, CSP, X-Frame-Options, etc.

Observability

• Prometheus Metrics - Request counts, latencies, cache hits
• OpenTelemetry Tracing - Distributed request tracing
• Audit Logging - Structured logs for compliance

Performance

• Redis Caching - Query response caching with smart TTL
• Circuit Breakers - Failure isolation per service
• Connection Pooling - Efficient gRPC connections

Quick Start

Prerequisites

• Go 1.21+
• Docker & Docker Compose
• Redis (for caching/rate limiting)

Running Locally

# Clone the repository
cd AmaniQuery

# Copy example config
cp gateway.example.yaml gateway.yaml

# Run with Docker Compose
cd deployments/docker
docker-compose up -d api-gateway

Configuration

See gateway.example.yaml for all options. Key settings:

server:
  bindAddr: ":8443"
  
auth:
  jwtSecret: "${JWT_SECRET}"
  
cache:
  redisAddr: "redis:6379"

Environment variables override config with GATEWAY_ prefix.

API Endpoints

Queries

Method	Path	Description
POST	/v2/queries	Execute RAG query
GET	/v2/queries/{id}	Get async query result
WS	/v2/queries/stream	Streaming query

Agents

Method	Path	Description
POST	/v2/agents	Create agent
GET	/v2/agents/{id}	Get agent
DELETE	/v2/agents/{id}	Delete agent
POST	/v2/agents/{id}/execute	Execute plan

Memory

Method	Path	Description
GET	/v2/memory/context	Get context window
POST	/v2/memory/sessions/{id}/consolidate	Consolidate memory

Admin

Method	Path	Description
GET	/admin/health	Health check
GET	/admin/metrics	Prometheus metrics

WebSocket Protocol

// Connect
const ws = new WebSocket('wss://api.example.com/v2/queries/stream?token=JWT');

// Send query
ws.send(JSON.stringify({
  type: 'query',
  payload: { query: 'What is RAG?', userId: 'user-123' }
}));

// Receive chunks
ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  if (msg.type === 'chunk') console.log(msg.data);
  if (msg.type === 'done') console.log('Complete');
};

Deployment

Docker

docker build -f deployments/docker/Dockerfile.gateway -t api-gateway .
docker run -p 8443:8443 api-gateway

Kubernetes

kubectl apply -f deployments/k8s/gateway.yaml

Project Structure

internal/gateway/
├── config.go           # Configuration
├── gateway.go          # Main server
├── types.go            # Request/response types
├── cache/
│   └── cache.go        # Redis cache
├── handlers/
│   ├── query.go        # Query endpoints
│   ├── websocket.go    # WebSocket streaming
│   ├── agent.go        # Agent CRUD
│   ├── memory.go       # Memory endpoints
│   ├── admin.go        # Health/metrics
│   └── auth.go         # Token endpoint
├── middleware/
│   ├── cors.go         # CORS handling
│   ├── ratelimit.go    # Rate limiting
│   ├── auth.go         # JWT + OPA auth
│   ├── audit.go        # Audit logging
│   └── tracing.go      # OpenTelemetry
├── observability/
│   └── metrics.go      # Prometheus metrics
└── services/
    ├── registry.go     # Service discovery
    └── clients.go      # gRPC clients

License

Apache 2.0