Puerta de enlace y enrutamiento API

1) El rol de la puerta de enlace API en la arquitectura

• recibe tráfico entrante (HTTP/HTTP2/HTTP3, WebSocket, gRPC);
• enrutamiento por reglas (host/path/headers/method/query/geo/peso/salud);
• aplica políticas end-to-end: autenticación/autorización, rate limiting, WAF, CORS, caché;
• realiza transformaciones (normalización de encabezados/cuerpos, gRPC↔JSON, GraphQL stitching);
• proporciona estabilidad (timeouts, retries, circuit-breaker, outlier detection);
• da la observancia y la facturación (registros, métricas, trazados, cuotas);
• aísla topología interna (mesh de servicio, servicios privados).

A menudo se utiliza en pareja: Edge/API-Gateway + Ingress/Mesh (Envoy/Istio/Linkerd) - el primero decide la política exterior, el segundo es east-west.

2) Topologías típicas

Puerta de enlace global única (CDN/edge POP → L7 gateway → servicios): simplemente, políticas centralizadas.
Gateways regionales (por-región) + Enrutamiento inteligente por geo/latencia.
Multi-tenant: rutas asignadas/subdominios/llaves, cuotas y límites por arrendatario.
Hybrid: on-prem + cloud, private link/peering, backends privados detrás de la puerta de enlace API.

3) Reglas de enrutamiento L7

• Host/Path: `api. example. com` → `/v1/orders/`.
• Headers: `X-Client`, `X-Region`, `User-Agent`, `Accept`.
• Método/Tipo de contenido: distinción JSON/Proto/GraphQL.
• Query/Fragment: cuidado - afecta a las opciones de caché/.
• Geo/Latency: RR/región más cercana, fallar en la degradación.
• Weighted/Canary: distribución de tráfico 90/10, 50/50, sticky por cookie.
• Session affinity: hash-based por clave/token (suavemente al escalar).

yaml nginx. ingress. kubernetes. io/canary: "true"
nginx. ingress. kubernetes. io/canary-weight: "10" # 10% traffic to new backend

yaml match: { prefix: "/orders", headers: [{name: "X-Experiment", exact_match: "new"}] }
route: { cluster: orders-v2 }

4) Protocolos e interoperabilidad

NAT/JSON: default, describa OpenAPI para validar/generar clientes.
gRPC - Proto binario en la parte superior de la HTTP/2; para clientes externos, utilice gRPC-JSON transcodificación.
GraphQL: agrega servicios; en el perímetro, controle la complexidad/profundidad de las solicitudes.
WebSocket/SSE - bidireccional/push; considere sticky y timeouts.
HTTP/2/3 (QUIC) - multiplexación/inicio rápido; compruebe la compatibilidad con WAF/proxy.

5) Seguridad: autenticación y autorización

5. 1 Transporte

TLS 1. 2 + en el perímetro, HSTS, OCSP stapling, PFS.
mTLS para V2V/API interna y máquina-a-máquina.
IP allowlist/denylist, geo-limites.

5. 2 Nivel de aplicación

OAuth2/OIDC: bearer-tokens JWT, verificación de firma/expiración/audiencia.
NMAS/firmas: fecha + línea canonizada + firma (AWS-similar) - protección contra sustitución, repetición (nonce/ventana de tiempo).
Claves API: sólo como identificador; derechos - a través de RBAC/ABAC/Scoups.
CORS: explícito allow-origin, pre-flight caché.
WAF: firmas (OWASP API Top 10), anormalidad, protección bot, campos JSON recursivos.
DDoS/Abuse: connection limiting, token-bucket/Leaky bucket, berst + velocidad media, banes dinámicos.

yaml plugins:
- name: oidc config: { issuer: "...", client_id: "...", client_secret: "...", scopes: ["orders. read"] }
- name: rate-limiting config: { minute: 600, policy: local }

6) Validación, transformación e interoperabilidad

Esquemas: validación del cuerpo/encabezados/parámetros por OpenAPI/JSON-Schema/Protobuf.
Transformaciones: normalización de campos, enmascaramiento de PII, adición de encabezados de correlación ('traceparent', 'x-request-id').
Versioning: 'Header: X-API-Version', prefijos '/v1 ', versionamiento de recursos; deprecation policy и Sunset.
Backward-compat: sólo campo add; evite los cambios «rompedores» sin una nueva versión.
Idempotency: `Idempotency-Key` для POST; gateway almacena las claves en Redis con TTL.

7) Sostenibilidad: políticas de interconexión

Timeouts: connect/read/write; impagos razonables (por ejemplo, 1s/5s/5s).
Retries: sólo para seguros e idempotentes; jitter, backoff exponential, máximo de intentos.
Circuit breaker: abrir en caso de errores/latencia; medio-abierto para muestras.
Detección de Outlier: sacar a las malas instancias de la piscina.
Bulkhead/competencia: límites a las solicitudes simultáneas por ruta.
Failover: activo/pasivo, degradación zonal.
Tráfico de sombras: una carrera V2 «gris» paralela a V1 (sin impacto en la respuesta) para comparar.

yaml circuit_breakers:
thresholds:
- priority: DEFAULT max_connections: 1024 max_pending_requests: 2048 max_retries: 3

8) Caché y rendimiento

HTTP-кеш: `Cache-Control`, `ETag/If-None-Match`, `Vary`, `stale-while-revalidate`.
Edge-caches/RR: CDN para las API estáticas y «caché» (GET idempotentes).
Compresión: 'gzip/br' (no comprimir ya comprimido).
Request collapsing («coalescing»): combinación de consultas paralelas idénticas.
Response shaping: campos/filtros, paginación (cursor-based), límites de cota.

9) Observabilidad y explotación

Метрики: `l7_req_total{route,method,code}`, `latency_ms{p50,p95,p99}`, `upstream_errors`, `retry_count`, `cb_state`, `429_rate`, `quota_usage{tenant}`.
Registros: estructurales, con 'trace _ id/span _ id', 'user _ id/tenant _ id', 'client _ ip'.
Tracks: W3C Trace Context ('traceparent', 'tracestate'), pulsa en los apstreams.
Auditoría: quién invocó qué, con qué derechos; Almacenamiento inmutable para API sensibles.
SLO/SLA: objetivo p99, presupuesto de errores; el nivel root es mejor que el nivel global.

10) Gestión del plan de ancho de banda

Quota per-tenant/clave/grupo de clientes, en min/hora/día.
Los límites de Burst + sustentados; bucket leaky para suavizar.
Fairness: cuando la sobrecarga es fair queuing en lugar de «el primer encontrado».
Prioridades: rutas del sistema/críticas con prioridad y grupos dedicados.

11) Gestión de cambios y lanzamientos

Canary/Blue-Green: enrutamiento de peso; promoción automática de SLO (error/latencia).
Características gates/banderas de fondo: incluir por título/token.
Validadores shadowing/diff: comparación de cuerpos/estados, tolerancias delta.
Staging: dominios/rutas dedicados ('staging. api... '), claves y cuotas individuales.

12) Ejemplos de configuraciones

12. 1 NGINX - gateway básico con límite y caché

nginx map $http_x_request_id $reqid { default $request_id; }

limit_req_zone $binary_remote_addr zone=perip:10m rate=10r/s;

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

security add_header Strict-Transport-Security "max-age = 31536000" always;

location /v1/ {
limit_req zone=perip burst=30 nodelay;
proxy_set_header X-Request-ID $reqid;
proxy_set_header Authorization $http_authorization;
proxy_connect_timeout 1s;
proxy_read_timeout 5s;

proxy_cache api_cache;
proxy_cache_valid 200 10s;
proxy_cache_use_stale error timeout updating;
proxy_pass http://orders-v1;
}
}

12. 2 Envoy - Enrutamiento por pesos y retrés

yaml routes:
- match: { prefix: "/orders" }
route:
weighted_clusters:
clusters:
- name: orders-v1 weight: 90
- name: orders-v2 weight: 10 retry_policy:
retry_on: "5xx,reset,connect-failure"
num_retries: 2 per_try_timeout: 2s

12. 3 Traefik - Middlevary y headers

yaml http:
middlewares:
secHeaders:
headers:
stsSeconds: 31536000 contentTypeNosniff: true routers:
api:
rule: "Host(`api. example. com`) && PathPrefix(`/v1`)"
service: svc-orders middlewares: ["secHeaders"]

13) Anti-patrones

Un límite global para todos - los «buenos vecinos» sufren debido a los «ruidosos».
Retraídas sin idempotencia → tomas de efectos (pagos, creación de entidades).
Ignorar 'timeout '/' max body size' → colgar/agotar los workers.
Mezcla de políticas edge y lógica empresarial en la puerta de enlace (carga perimetral).
La falta de validación de los circuitos → la fragilidad de los clientes y los lanzamientos «rompedores».
WebSocket desnudo sin tener en cuenta los límites de auth/idle-time.
Secretos en los titulares sin rotación; ausencia de mTLS en el B2B interno.

14) Pruebas de reproducción (Días de juego)

Tormenta de solicitudes: verificación limiter/quota, comportamiento 429, degradación.
Pérdida de un clúster: failover/sobreasignación de peso; SLO canarios.
Respuestas pesadas: max body/timeouts; cortar conexiones.
Inyecciones/anomalías: reglas WAF, prohibición de JSON recursivo, grandes profundidades de GraphQL.
Error de rastreo: verificación de propagación 'traceparent' y sampling.
Secretos: rotación de claves/JWKS, caducidad de tokens, tolerancia clock-skew.

15) Lista de verificación de implementación

• Dominios/rutas/versiones definidas, publicado por OpenAPI/Proto.
• Personalizados TLS/mTLS, HSTS, gestión secreta y rotación.
• Autenticación incluida (OIDC/HMAC), RBAC/Scoops, CORS.
• Límites/cuotas per-tenant, colas justas, 429-UX.
• Enrutamiento por escalas/cabeceras, plan canario y rollback.
• Políticas timeout/retry/circuit-breaker/outlier.
• Validación de esquemas, transformaciones, enmascaramiento de PII.
• Edge-кеш/ETag, coalescing, gzip/br.
• Observabilidad: métricas, registros, pistas, dashboards y alertas.
• Runbooks: incidentes, rotación de llaves, listas de bloques, Black Friday.

16) FAQ

P: ¿En qué se diferencia la puerta de enlace API de la mecha de servicio?
R: La puerta de enlace es norte-sur (perímetro exterior, políticas de extremo a extremo). Mesh es east-west (conectividad intraclástrica/MTLS/retrae). A menudo se utilizan juntos.

P: ¿Dónde implementar auth: en gateway o servicios?
R: Ambos niveles: gateway - coarse-grained (autenticación, derechos básicos/cuotas), servicio - fine-grained (roles/atributos de dominio).

P: ¿Cuándo necesita gRPC-JSON transcodificación?
R: Cuando el gRPC interno, y hacia fuera, se requiere NAT/JSON y simples clientes/navegadores.

P: ¿Cómo elegir una estrategia de versionamiento?
R: Para las API públicas, la ruta de acceso es '/vN '+ los encabezados de la privación y el largo overlap. Para interiores, los indicadores de capacidad/esquema de compatibilidad.

17) Resultados

La puerta de enlace de la API no es solo un «proxy», sino un centro de políticas y sostenibilidad. El correcto enrutamiento, seguridad, límites, validación y observabilidad dan previsibilidad y velocidad a las liberaciones. Combine la puerta de enlace edge con la mecha de servicio, automatice los canarios y las cuotas, pruebe las fallas - y el perímetro se convertirá en su acelerador, no en un cuello de botella.