Skip to main content

API Gateway - Visión General

El API Gateway de IRIS es el punto de entrada central de la plataforma IDP (Intelligent Document Processing). Construido con Express.js y Node.js, orquesta la comunicación entre los microservicios Python y proporciona una interfaz unificada para clientes. El OCR sigue estando presente como componente del pipeline (Fases 5-6) para la extracción de texto especializada.

🎯 Propósito y Responsabilidades​

Funciones Principales​

  • 🔐 Autenticación y Autorización: Sistema JWT completo con tokens de acceso y refresh
  • 🔀 Orquestación de Microservicios: Coordina llamadas a los 4 microservicios Python
  • 🛡️ Seguridad y Middleware: Rate limiting, CORS, helmet, validación de datos
  • 📚 Documentación Automática: Swagger/OpenAPI integrado con interfaz interactiva
  • 📊 Monitoreo y Logging: Sistema de logs estructurado y métricas de rendimiento
  • ⚡ Cache y Optimización: Gestión eficiente de requests y respuestas

Arquitectura del Gateway​

🏗️ Stack Tecnológico​

Core Framework​

  • Express.js: Framework web minimalista y flexible
  • Node.js 16+: Runtime JavaScript de alto rendimiento
  • npm/yarn: Gestión de dependencias y scripts

Middleware y Seguridad​

  • Helmet: Protección de headers HTTP
  • CORS: Configuración de Cross-Origin Resource Sharing
  • express-rate-limit: Protección contra ataques DDoS
  • express-validator: Validación robusta de datos de entrada
  • compression: Compresión GZIP automática

Autenticación y Autorización​

  • jsonwebtoken: Generación y verificación de tokens JWT
  • bcryptjs: Hashing seguro de contraseñas
  • passport.js: Estrategias de autenticación flexibles
  • express-session: Gestión de sesiones servidor

Documentación y Validación​

  • swagger-jsdoc: Generación automática de documentación OpenAPI
  • swagger-ui-express: Interfaz interactiva para documentación
  • joi: Esquemas de validación de datos robustos
  • ajv: Validación JSON Schema de alto rendimiento

Logging y Monitoreo​

  • winston: Sistema de logging estructurado
  • morgan: Logging de requests HTTP
  • prometheus-client: Métricas para monitoreo
  • express-status-monitor: Dashboard de métricas en tiempo real

🔌 Endpoints Principales​

Autenticación​

POST /api/v1/auth/register     # Registro de usuarios
POST /api/v1/auth/login        # Inicio de sesión
POST /api/v1/auth/refresh      # Renovación de tokens
GET  /api/v1/auth/profile      # Perfil de usuario
POST /api/v1/auth/logout       # Cierre de sesión

Pipeline Completo​

POST /api/v1/pipeline/process  # Ejecutar pipeline completo
GET  /api/v1/pipeline/status   # Estado del procesamiento
GET  /api/v1/pipeline/history  # Historial de procesamientos

Fases Individuales​

POST /api/v1/phases/preprocess    # Fase 1: Preprocesamiento
POST /api/v1/phases/embeddings    # Fase 2: Embeddings
POST /api/v1/phases/classify      # Fase 3-4: Clasificación
POST /api/v1/phases/extract       # Fase 5-6: Extracción (IDP) con OCR

Administración​

GET  /health                   # Health check del sistema
GET  /api                      # Información general de la API
GET  /api-docs                 # Documentación Swagger
GET  /metrics                  # Métricas de Prometheus

🛡️ Seguridad Implementada​

Autenticación JWT​

  • Access Tokens: Corta duración (1 hora) para operaciones
  • Refresh Tokens: Larga duración (7 días) para renovación
  • Rotación Automática: Tokens rotan en cada renovación
  • Revocación: Lista negra de tokens comprometidos

Rate Limiting​

// Configuración por defecto
{
  windowMs: 15 * 60 * 1000,  // 15 minutos
  max: 100,                  // 100 requests por ventana
  message: "Demasiadas solicitudes"
}

// Endpoints críticos
{
  max: 10,                   // Límite más estricto
  skipSuccessfulRequests: true
}

Validación de Datos​

  • Joi Schemas: Validación estricta de payload
  • Sanitización: Limpieza automática de datos de entrada
  • Type Checking: Verificación de tipos de datos
  • Custom Validators: Validaciones específicas del dominio

📈 Monitoreo y Métricas​

Métricas Recolectadas​

  • Request Duration: Tiempo de respuesta por endpoint
  • Request Count: Número de requests por minuto/hora
  • Error Rate: Porcentaje de errores 4xx/5xx
  • Memory Usage: Uso de memoria del proceso Node.js
  • CPU Usage: Utilización de CPU
  • Microservice Health: Estado de conexión con servicios Python

Dashboards Disponibles​

  • Health Check Dashboard: /health - Estado general del sistema
  • Status Monitor: /status - Métricas en tiempo real
  • Prometheus Metrics: /metrics - Exportación para Grafana
  • Swagger UI: /api-docs - Documentación interactiva

🔄 Comunicación con Microservicios​

Patrón de Comunicación​

// Ejemplo de llamada a microservicio
const response = await fetch(`${MICROSERVICE_URL}/endpoint`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Request-ID': generateRequestId(),
    'Authorization': `Bearer ${serviceToken}`
  },
  body: JSON.stringify(payload),
  timeout: 30000
});

Manejo de Errores​

  • Circuit Breaker: Protección contra servicios caídos
  • Retry Logic: Reintentos automáticos con backoff exponencial
  • Fallback Responses: Respuestas por defecto en caso de falla
  • Health Checks: Verificación periódica de servicios

Load Balancing​

  • Round Robin: Distribución equitativa de requests
  • Health-based: Exclusión automática de servicios no saludables
  • Weighted Distribution: Balanceo basado en capacidad de servicios

🚀 Configuración y Deployment​

Variables de Entorno​

# Configuración básica
NODE_ENV=production
PORT=3000
API_VERSION=1.0.0

# JWT Configuration
JWT_ACCESS_SECRET=your-secret-key
JWT_REFRESH_SECRET=your-refresh-secret
JWT_ACCESS_EXPIRY=1h
JWT_REFRESH_EXPIRY=7d

# Microservices URLs
IMAGE_PROCESSOR_URL=http://localhost:8001
ML_EMBEDDINGS_URL=http://localhost:8002
ML_CLASSIFIER_URL=http://localhost:8003
OCR_EXTRACTOR_URL=http://localhost:8004

# Rate Limiting
RATE_LIMIT_WINDOW=900000
RATE_LIMIT_MAX=100

Docker Configuration​

FROM node:18-alpine AS production
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
EXPOSE 3000
CMD ["npm", "start"]

📚 Próximos Pasos​

¿Tienes preguntas sobre el API Gateway? Consulta la documentación interactiva o revisa los ejemplos de uso.