docs/API_GATEWAY_DESIGN.md

Unified API Gateway Design

Date: 2025-01-27 Purpose: Design document for unified API gateway Status: Design Document

---

Executive Summary

This document outlines the design for a unified API gateway that will serve as a single entry point for all workspace projects, providing centralized authentication, rate limiting, and API versioning.

---

Architecture Overview

Components

1. API Gateway (Kong, Traefik, or custom)
2. Authentication Service (Keycloak, Auth0, or custom)
3. Rate Limiting Service (Redis-based)
4. API Versioning (Path-based or header-based)
5. Monitoring & Logging (Prometheus, Grafana, Loki)

Architecture Diagram

Client
  ↓
API Gateway (Kong/Traefik)
  ├── Authentication Layer
  ├── Rate Limiting
  ├── Request Routing
  └── Response Aggregation
  ↓
Backend Services
  ├── dbis_core
  ├── the_order
  ├── Sankofa
  └── Other services

---

Features

1. Authentication & Authorization

Methods:

• JWT tokens
• API keys
• OAuth2/OIDC
• mTLS (for service-to-service)

Implementation:

• Centralized authentication service
• Token validation
• Role-based access control (RBAC)
• Permission checking

2. Rate Limiting

Strategies:

• Per-user rate limits
• Per-API rate limits
• Per-IP rate limits
• Tiered rate limits (free, paid, enterprise)

Storage: Redis for distributed rate limiting

3. API Versioning

Strategy: Path-based versioning

• /v1/api/...
• /v2/api/...

Alternative: Header-based (Accept: application/vnd.api+json;version=2)

4. Request Routing

Features:

• Path-based routing
• Header-based routing
• Load balancing
• Health checks
• Circuit breakers

5. Monitoring & Observability

Metrics:

• Request rate
• Response times
• Error rates
• Authentication failures
• Rate limit hits

Logging:

• All requests logged
• Structured logging (JSON)
• Centralized log aggregation

---

Technology Options

Option 1: Kong Gateway (Recommended)

Pros:

• Feature-rich
• Plugin ecosystem
• Good documentation
• Enterprise support available

Cons:

• More complex setup
• Higher resource usage

Option 2: Traefik

Pros:

• Kubernetes-native
• Auto-discovery
• Simpler setup
• Lower resource usage

Cons:

• Fewer built-in features
• Less mature plugin ecosystem

Option 3: Custom (Node.js/TypeScript)

Pros:

• Full control
• Custom features
• Lightweight

Cons:

• More development time
• Maintenance burden

Recommendation: Kong Gateway for production, Traefik for simpler setups

---

Implementation Plan

Phase 1: Basic Gateway (Weeks 1-2)

• Deploy API gateway (Kong or Traefik)
• Set up basic routing
• Configure SSL/TLS
• Set up monitoring

Phase 2: Authentication (Weeks 3-4)

• Integrate authentication service
• Implement JWT validation
• Set up RBAC
• Test authentication flow

Phase 3: Rate Limiting (Weeks 5-6)

• Set up Redis for rate limiting
• Configure rate limit rules
• Implement tiered limits
• Test rate limiting

Phase 4: Advanced Features (Weeks 7-8)

• API versioning
• Request/response transformation
• Caching
• WebSocket support

Phase 5: Migration (Weeks 9-12)

• Migrate dbis_core to gateway
• Migrate the_order to gateway
• Migrate Sankofa to gateway
• Migrate other services
• Complete testing

---

Configuration Example

Kong Gateway Configuration

services:
  - name: dbis-core
    url: http://dbis-core:3000
    routes:
      - name: dbis-core-v1
        paths:
          - /v1/dbis
        plugins:
          - name: rate-limiting
            config:
              minute: 100
              hour: 1000
          - name: jwt
            config:
              secret_is_base64: false

Traefik Configuration

http:
  routers:
    dbis-core:
      rule: "PathPrefix(`/v1/dbis`)"
      service: dbis-core
      middlewares:
        - auth
        - rate-limit
  services:
    dbis-core:
      loadBalancer:
        servers:
          - url: "http://dbis-core:3000"

---

Security Considerations

Authentication

• JWT tokens with short expiration
• Refresh token rotation
• Token revocation
• Secure token storage

Rate Limiting

• Prevent DDoS attacks
• Protect against abuse
• Fair resource allocation

Network Security

• mTLS for service-to-service
• WAF (Web Application Firewall)
• DDoS protection
• IP whitelisting (optional)

---

Monitoring & Alerting

Key Metrics

• Request rate per service
• Response times (p50, p95, p99)
• Error rates
• Authentication failures
• Rate limit hits
• Gateway health

Alerts

• High error rate
• Slow response times
• Authentication failures spike
• Rate limit exhaustion
• Gateway downtime

---

Success Metrics

• Single entry point for all APIs
• Centralized authentication operational
• Rate limiting functional
• 80% of projects migrated to gateway
• 50% reduction in authentication code duplication
• Improved API security posture

---

Last Updated: 2025-01-27 Next Review: After Phase 1 completion