InfraNotes API Gateway Documentation

Welcome to the InfraNotes API Gateway documentation. This gateway provides secure, scalable, and observable routing to backend services with advanced features like JWT authentication, rate limiting, circuit breakers, and distributed tracing.

📚 Documentation Structure

API Specification

OpenAPI Specification - Complete OpenAPI 3.1 specification for gateway management endpoints

Guides

Authentication Guide - JWT/JWKS authentication, token requirements, RBAC, and troubleshooting
Rate Limiting Guide - Rate limiting algorithms, headers, error handling, and best practices
Routing Guide - Request routing, path matching, load balancing, circuit breakers, and health checks
Error Handling Guide - Standard error formats, status codes, and debugging
Observability Guide - Metrics, tracing, logging, and monitoring

Reference

Configuration Schema - Complete configuration reference with examples
Gateway Assessment - Technical assessment and architecture decisions

🚀 Quick Start

1. Understanding the Gateway

The InfraNotes API Gateway is a thin gateway focused on:

Routing: Path-based routing to backend services
Authentication & Authorization: JWT/JWKS with RS256, RBAC, scope-based access
Quality of Service: Rate limiting, circuit breakers, load balancing, health checks
Observability: OpenTelemetry tracing, Prometheus metrics, structured logging

What the gateway does NOT do:

Business logic (handled by backend services)
Data transformation (minimal header forwarding only)
API composition (no aggregation of multiple services)

2. Gateway Endpoints

The gateway exposes two types of endpoints:

Gateway Management Endpoints (handled by gateway)

GET  /health                          # Basic health check
GET  /ready                           # Readiness probe
GET  /live                            # Liveness probe
GET  /health/detailed                 # Detailed health status
GET  /metrics/detailed                # Prometheus metrics (privileged)
GET  /observability/metrics           # Metrics summary
GET  /observability/tracing           # Tracing status
GET  /observability/performance       # Performance monitoring
GET  /observability/dashboard         # Combined observability data
GET  /openapi/gateway.json            # OpenAPI specification
GET  /docs                            # Documentation links

# JWT Service Discovery (if enabled)
POST   /api/v1/service-discovery/register
DELETE /api/v1/service-discovery/deregister/{instanceId}
GET    /api/v1/service-discovery/discover
GET    /api/v1/service-discovery/services/{serviceType}
GET    /api/v1/service-discovery/health

Proxied Endpoints (forwarded to backend services)

All other endpoints are proxied to backend services based on routing configuration. The gateway routes to three main services:

Main Application (infranotes.preprod-1.svc.cluster.local:8080) - Auth, budgets, invoices, payments, projects, teams
Analytics Module (infranotes-module.preprod-1.svc.cluster.local:8080) - Documents, transactions, analytics, planning, goals
Project Finance (infranotes-project-finance.preprod-1.svc.cluster.local:8080) - Project finance, phases, milestones

Example Routes:

# Main Application
POST /api/auth/login                  # Authentication (public)
GET  /api/invoices/*                  # Invoice management
GET  /api/payments/*                  # Payment processing
GET  /api/projects/*                  # Project management

# Financial Intelligence
GET  /api/v1/intelligence/budgets/*   # Canonical budget management

# Accounting Workspace
GET  /api/v1/accounting/ledger/*      # Ledger APIs
GET  /api/v1/accounting/recon/*       # Reconciliation APIs
GET  /api/v1/accounting/reports/*     # Reporting APIs

# Analytics Module
GET  /api/documents/*                 # Document management
GET  /api/transactions/*              # Transaction management
GET  /api/analytics/*                 # Analytics and reporting
GET  /api/planning/*                  # Financial planning

# Project Finance
GET  /api/analytics/portfolio         # Portfolio analytics
GET  /api/project-finance/*           # Project finance
GET  /api/milestones/*                # Milestones

Note: Complete route configuration is in infraforge-argocd/apps/infranotes-gateway/base/values.yaml

3. Making Authenticated Requests

# 1. Obtain JWT token from InfraNotes auth service
TOKEN=$(curl -X POST https://gateway.infraforg.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your-password"
  }' | jq -r '.access_token')

# 2. Make authenticated requests to different services
# Get budgets (Main Application)
curl https://gateway.infraforg.com/api/budgets \
  -H "Authorization: Bearer $TOKEN"

# Get invoices (Main Application)
curl https://gateway.infraforg.com/api/invoices \
  -H "Authorization: Bearer $TOKEN"

# Get analytics (Analytics Module)
curl https://gateway.infraforg.com/api/analytics/portfolio \
  -H "Authorization: Bearer $TOKEN"

# Get project finance (Project Finance Service)
curl https://gateway.infraforg.com/api/project-finance/123 \
  -H "Authorization: Bearer $TOKEN"

4. Handling Rate Limits

# Check rate limit headers in response
curl -i https://gateway.infraforg.com/api/budgets \
  -H "Authorization: Bearer $TOKEN"

# Response headers:
# X-RateLimit-Limit: 5000
# X-RateLimit-Remaining: 4875
# X-RateLimit-Reset: 1735041600

# Authentication endpoints have lower limits (50 req/window)
curl -i https://gateway.infraforg.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "pass"}'

# Response headers:
# X-RateLimit-Limit: 50
# X-RateLimit-Remaining: 45
# X-RateLimit-Reset: 1735041600

5. Monitoring the Gateway

# Health check (public)
curl https://gateway.infraforg.com/health

# Detailed health with component status (public)
curl https://gateway.infraforg.com/health/detailed

# Metrics summary (requires admin role)
curl https://gateway.infraforg.com/observability/metrics \
  -H "Authorization: Bearer $ADMIN_TOKEN"

# Prometheus metrics (requires admin role)
curl https://gateway.infraforg.com/metrics/detailed \
  -H "Authorization: Bearer $ADMIN_TOKEN"

🔑 Key Features

Authentication & Authorization

JWT/JWKS: RS256 algorithm with JWKS URL-based key fetching
Token Caching: Redis-backed caching for performance
RBAC: Role-based access control
Scope-Based Access: OAuth 2.0 scope validation
Audience Validation: Multi-tenant audience support

Read the Authentication Guide →

Rate Limiting

Multiple Algorithms: Sliding window, token bucket, fixed window
Multi-Level: User, IP, and global rate limiting
Redis-Backed: Distributed rate limiting with Lua scripts
Fallback: In-process rate limiting when Redis unavailable
Standard Headers: X-RateLimit-* headers on all responses

Read the Rate Limiting Guide →

Circuit Breakers & Health Checks

Automatic Failover: Circuit breakers protect backend services
Active Health Checks: Periodic health checks with configurable thresholds
Health-Aware Routing: Unhealthy backends removed from pool
Graceful Degradation: 503 responses when all backends unhealthy

Read the Routing Guide →

Load Balancing

Multiple Strategies: Round robin, least connections, weighted, health-aware
Session Affinity: Sticky sessions support
Dynamic Discovery: Kubernetes EndpointSlice-based discovery
JWT Service Discovery: Dynamic service registration and discovery

Read the Routing Guide →

Observability

OpenTelemetry: Unified tracing and metrics with DataDog OTLP exporter
Prometheus Metrics: Comprehensive metrics for monitoring
Structured Logging: JSON logs with Zap logger
Distributed Tracing: W3C Trace Context propagation
Performance Monitoring: Memory, CPU, goroutines, GC metrics

Read the Observability Guide →

Security

DDoS Protection: Connection limits, request rate limits, slow request timeouts
IP Filtering: Whitelist/blacklist with auto-blocking
Content Filtering: MIME type detection, ICAP/ClamAV malware scanning
Security Headers: HSTS, CSP, X-Frame-Options, X-Content-Type-Options
Header Spoofing Prevention: Auth headers removed from incoming requests

Read the Error Handling Guide →

📖 Common Use Cases

Use Case 1: Authenticated API Request

# Get budgets from Main Application
curl https://gateway.infraforg.com/api/budgets \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

# Get analytics from Analytics Module
curl https://gateway.infraforg.com/api/analytics/portfolio \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

# Get project finance from Project Finance Service
curl https://gateway.infraforg.com/api/project-finance/123 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

Use Case 2: Handling Rate Limits

import time
import requests

def make_request_with_retry(url, token):
    response = requests.get(url, headers={"Authorization": f"Bearer {token}"})
    
    if response.status_code == 429:
        retry_after = int(response.headers.get("Retry-After", 60))
        print(f"Rate limited. Waiting {retry_after} seconds...")
        time.sleep(retry_after)
        return make_request_with_retry(url, token)
    
    return response.json()

Use Case 3: Debugging with Request IDs

# All errors include request_id
curl https://gateway.infraforg.com/api/budgets

# Response:
# {
#   "error": "unauthorized",
#   "message": "Authorization header required",
#   "request_id": "550e8400-e29b-41d4-a716-446655440000"
# }

# Search logs for request in Kubernetes
kubectl logs -l app=infranotes-gateway -n preprod-1 | grep "550e8400-e29b-41d4-a716-446655440000"

# Or search in DataDog
# Use the request_id to trace the request through all services

🛠️ Configuration

See config.yaml for complete configuration reference.

Key configuration sections:

app: Application metadata (name, version, environment)
server: HTTP server settings (port, timeouts)
jwt: JWT authentication configuration
rate_limiting: Rate limiting rules and algorithms
security: DDoS protection, IP filtering, content scanning
circuit_breakers: Circuit breaker settings
load_balancing: Load balancing strategies
observability: Metrics, tracing, logging configuration

🐛 Troubleshooting

📊 Monitoring & Alerting

See Observability Guide for:

Prometheus metrics and queries
Grafana dashboard setup
Alert rules and thresholds
Log aggregation and searching
Distributed tracing setup

🤝 Support

For issues or questions:

Check the relevant guide in this documentation
Search logs using request IDs from error responses
Check Prometheus metrics for anomalies
Review DataDog traces for performance issues
Contact the InfraNotes team with request IDs and logs

📝 License

Proprietary - InfraNotes Platform