Patrones de puerta de enlace API y mejores prácticas para aplicaciones modernas

Las puertas de enlace API manejan un promedio del 83 % de todo el tráfico empresarial y sirven como punto de entrada único para las aplicaciones cliente. Una puerta de enlace API bien diseñada simplifica la comunicación cliente-servidor, aplica políticas de seguridad y proporciona observabilidad en todos los servicios. Uno mal diseñado se convierte en un cuello de botella y un único punto de falla.

Esta guía cubre los patrones de arquitectura de puerta de enlace API, la selección de tecnología y las mejores prácticas de implementación para aplicaciones web, sistemas ERP y plataformas de comercio electrónico.

Conclusiones clave

• Las puertas de enlace API centralizan inquietudes transversales (autenticación, limitación de velocidad, registro) para eliminar la duplicación entre servicios.
• La limitación de velocidad a nivel de puerta de enlace protege los servicios backend de picos de tráfico y abusos.
• Los patrones de disyuntores evitan fallas en cascada cuando los servicios posteriores no están en buen estado
• El control de versiones de API a través de la puerta de enlace permite una evolución compatible con versiones anteriores de su superficie API

---

Patrones de puerta de enlace principales

Patrón 1: Solicitar enrutamiento

La puerta de enlace enruta las solicitudes al servicio backend apropiado según la ruta URL, los encabezados u otros atributos de la solicitud.

# Nginx as API gateway
upstream api_service {
    server api-1:3001;
    server api-2:3001;
}

upstream auth_service {
    server auth:9000;
}

upstream web_service {
    server web:3000;
}

server {
    listen 443 ssl;
    server_name api.example.com;

    location /api/v1/ {
        proxy_pass http://api_service;
    }

    location /auth/ {
        proxy_pass http://auth_service;
    }

    location / {
        proxy_pass http://web_service;
    }
}

Patrón 2: Autenticación y autorización

Centralizar la autenticación en el gateway para evitar implementarla en todos los servicios.

// NestJS middleware for JWT validation at the gateway level
@Injectable()
export class GatewayAuthMiddleware implements NestMiddleware {
  constructor(private readonly jwtService: JwtService) {}

  async use(req: Request, res: Response, next: NextFunction) {
    // Skip public endpoints
    if (this.isPublicEndpoint(req.path)) {
      return next();
    }

    const token = this.extractToken(req);
    if (!token) {
      throw new UnauthorizedException('Missing authentication token');
    }

    try {
      const payload = await this.jwtService.verifyAsync(token);
      req['user'] = payload;
      next();
    } catch {
      throw new UnauthorizedException('Invalid token');
    }
  }

  private extractToken(req: Request): string | undefined {
    // Check cookie first, then Authorization header
    return req.cookies?.ecosire_auth
      || req.headers.authorization?.replace('Bearer ', '');
  }

  private isPublicEndpoint(path: string): boolean {
    const publicPaths = ['/health', '/api/v1/products', '/api/v1/blog'];
    return publicPaths.some(p => path.startsWith(p));
  }
}

Patrón 3: limitación de velocidad

// Rate limiting configuration per endpoint type
const rateLimits = {
  public: { windowMs: 60000, max: 100 },     // 100 req/min for public APIs
  authenticated: { windowMs: 60000, max: 500 }, // 500 req/min for authenticated users
  admin: { windowMs: 60000, max: 1000 },       // 1000 req/min for admin
  webhooks: { windowMs: 60000, max: 50 },       // 50 req/min for webhooks
};

Patrón 4: Disyuntor

Cuando falla un servicio aguas abajo, el disyuntor evita fallas en cascada:

[Closed] --> (failures exceed threshold) --> [Open] --> (timeout expires) --> [Half-Open]
    ^                                                                            |
    |                                        (success)                           |
    +--------------------------------------------------------------------<-------+
    |                                        (failure)                           |
    |                                           +-------->  [Open]

Estados:

• Cerrado: las solicitudes pasan normalmente. Seguimiento del recuento de errores.
• Abierto: todas las solicitudes fallan inmediatamente sin llamar al servicio. Devuelve una respuesta en caché/de reserva.
• Medio abierto: permite el paso de una solicitud. Si tiene éxito, cierre el circuito. Si falla, vuelva a abrir.

Patrón 5: almacenamiento en caché de respuestas

# Cache GET responses for public endpoints
proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=api_cache:10m max_size=1g inactive=60m;

location /api/v1/products {
    proxy_pass http://api_service;
    proxy_cache api_cache;
    proxy_cache_valid 200 5m;
    proxy_cache_valid 404 1m;
    proxy_cache_key "$scheme$request_method$host$request_uri";
    add_header X-Cache-Status $upstream_cache_status;
}

---

Estrategias de control de versiones de API

Recomendación: control de versiones de la ruta URL. Es el más explícito, el más depurable y el más fácil de enrutar a nivel de puerta de enlace.

Cambios importantes frente a cambios no importantes

---

Comparación de tecnología de puerta de enlace

Para la mayoría de las PYMES: Nginx es suficiente. Maneja enrutamiento, terminación SSL, limitación de velocidad y almacenamiento en caché con una sobrecarga de menos de un milisegundo. Actualice a Kong cuando necesite capacidades avanzadas de complementos (OAuth2, transformación de solicitudes, análisis).

---

Observabilidad en la puerta de enlace

Solicitar registro

log_format gateway '$remote_addr - $remote_user [$time_local] '
                   '"$request" $status $body_bytes_sent '
                   '"$http_referer" "$http_user_agent" '
                   '$request_time $upstream_response_time '
                   '$http_x_request_id';

access_log /var/log/nginx/gateway.log gateway;

Colección de métricas

Realice un seguimiento de estas métricas a nivel de puerta de enlace:

• Tasa de solicitudes por punto final, método y código de estado
• Distribución de latencia (P50, P95, P99) por punto final
• Tasa de errores por punto final y tipo de error
• Límite de tarifas alcanzadas por cliente
• Proporción de aciertos de caché por punto final
• Tiempo de respuesta ascendente frente al tiempo de respuesta total

---

Manejo de errores en la puerta de enlace

Respuestas de error consistentes

La puerta de enlace debería normalizar las respuestas de error de diferentes servicios de backend:

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "The requested service is temporarily unavailable",
    "requestId": "req_abc123",
    "timestamp": "2026-03-16T14:32:01Z"
  }
}

Configuración de reintento y tiempo de espera

location /api/ {
    proxy_pass http://api_service;

    # Timeout configuration
    proxy_connect_timeout 5s;
    proxy_send_timeout 30s;
    proxy_read_timeout 30s;

    # Retry on connection errors only (not on 5xx)
    proxy_next_upstream error timeout;
    proxy_next_upstream_tries 2;

    # Custom error pages
    error_page 502 503 504 /api-error.json;
}

Degradación elegante

Cuando un servicio backend no crítico no funciona, la puerta de enlace puede ofrecer respuestas almacenadas en caché o datos alternativos en lugar de devolver errores:

---

Patrones de seguridad de puerta de enlace

Solicitar validación

Valide la estructura de la solicitud antes de reenviarla a los servicios de backend:

• Rechazar solicitudes con tipos de contenido desconocidos
• Aplicar el tamaño máximo del cuerpo de la solicitud por punto final
• Validar los encabezados requeridos (versión API, tipo de contenido)
• Elimina los encabezados sospechosos (encabezados salto por salto, encabezados internos del servidor)

Lista de direcciones IP permitidas para terminales de administración

location /api/admin/ {
    allow 203.0.113.0/24;  # Office IP range
    allow 10.0.0.0/8;      # Internal network
    deny all;

    proxy_pass http://api_service;
}

Solicitar transformación

La puerta de enlace puede agregar, modificar o eliminar encabezados antes de reenviar:

location /api/ {
    proxy_pass http://api_service;

    # Add security headers
    proxy_set_header X-Request-ID $request_id;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Real-IP $remote_addr;

    # Remove internal headers from responses
    proxy_hide_header X-Powered-By;
    proxy_hide_header Server;
}

---

Preguntas frecuentes

¿Necesitamos una puerta de enlace API para una aplicación monolítica?

Sí, pero uno más sencillo. Incluso para un monolito, Nginx como proxy inverso proporciona terminación SSL, limitación de velocidad, servicio de archivos estáticos y encabezados de seguridad. No necesita Kong o AWS API Gateway para un monolito, pero sí necesita algo entre Internet y su servidor de aplicaciones.

¿Cómo manejamos la conmutación por error de la puerta de enlace API?

Ejecute varias instancias de puerta de enlace detrás de un equilibrador de carga en la nube (AWS ALB, Cloudflare). Si una instancia de puerta de enlace falla, el equilibrador de carga enruta el tráfico a instancias en buen estado. Para Nginx, utilice comprobaciones de estado activas y eliminación automática de flujos ascendentes en mal estado.

¿La puerta de enlace API debería manejar la autenticación o debería hacerlo cada servicio?

La puerta de enlace debe manejar la autenticación (verificar que el token sea válido). Los servicios individuales deben manejar la autorización (verificar si el usuario autenticado tiene permiso para la acción específica). Esta separación mantiene la puerta de enlace liviana y permite que los servicios tomen decisiones detalladas de control de acceso.

¿Cómo manejamos CORS en la puerta de enlace API?

Configure CORS en el nivel de puerta de enlace para evitar la duplicación de encabezados CORS entre servicios. Configure Access-Control-Allow-Origin para sus dominios de interfaz específicos (nunca use * en producción con credenciales). Maneje las solicitudes de OPCIONES de verificación previa en la puerta de enlace para reducir la carga en los servicios backend.

---

¿Qué viene después?

Una puerta de enlace API es la puerta de entrada a su infraestructura. Combínelo con monitoreo para visibilidad, refuerzo de seguridad para protección y pruebas de carga para planificación de capacidad.

Comuníquese con ECOSIRE para obtener consultoría sobre arquitectura API, o explore nuestra guía DevOps para obtener la hoja de ruta completa de infraestructura.

---

Publicado por ECOSIRE: ayuda a las empresas a crear una infraestructura API escalable.