API management y API gateways: políticas, rate limiting, planes y portales

En cuanto una API tiene consumidores que no controlas, aparece un conjunto de preocupaciones que no tiene nada que ver con su comportamiento de negocio. ¿Quién llama? ¿Tiene permiso? ¿Con qué frecuencia puede llamar? ¿Cómo damos de alta a los próximos cien desarrolladores sin una reunión con cada uno? ¿Qué endpoints se usan de verdad, quién los usa y qué rendimiento tienen? Incorporar las respuestas en cada servicio significa construirlas una y otra vez, y de forma incoherente. Un API gateway las concentra en el borde; una plataforma de API management añade a su alrededor la capa comercial y organizativa.

La distinción importa a la hora de elegir herramientas, porque «gateway» se usa para productos cuya complejidad abarca tres órdenes de magnitud: desde un centenar de líneas de configuración de un proxy hasta una suite con portal, integración de facturación y un flujo de trabajo de gobernanza. Esta guía separa la función técnica de la función de gestión, y deja claro qué problemas justifican qué inversión.

Qué hay en el recorrido de la petición

Entre un cliente y un servicio suelen aparecer cuatro componentes, y es habitual confundirlos.

Un balanceador de carga conoce instancias, no APIs; no puede saber que POST /transfers merece un límite de peticiones distinto al de GET /rates. Un reverse proxy añade conocimiento de las rutas, pero ninguna noción de identidad del consumidor ni de cuota. El API gateway es el primer componente que entiende quién llama a qué operación con qué plan, y eso es lo que hace posible aplicar políticas.

El mesh está en otro eje. Los gateways gestionan el tráfico norte–sur —el que entra y sale del sistema—, mientras que un mesh gestiona el tráfico este–oeste entre servicios internos. Se solapan en reintentos y mTLS, pero son complementarios más que rivales: la mayoría de las plataformas que usan un mesh siguen poniendo un gateway en el borde, y muchos sistemas necesitan un gateway sin necesitar mesh alguno. El trade-off del mesh se trata con más detalle en patrones de diseño de microservicios.

Lo que diferencia al gateway del enterprise service bus es la intención. Ambos median, pero el bus se diseñó para alojar lógica de integración y creció hasta contener las reglas de negocio de la empresa, mientras que un gateway se mantiene fino a propósito. SOA y el ESB explica cómo salió mal aquello; la lección que conviene retener es que cualquier decisión de negocio dentro del gateway es una decisión que los tests de tu servicio no ven.

Políticas que aplica el gateway

El comportamiento de un gateway se expresa como una cadena de políticas que se evalúan en cada petición. La sintaxis concreta varía; las categorías, no.

• Control de tráfico — límites de peticiones, cuotas, topes de concurrencia, límites de tamaño de petición, listas de IP permitidas y denegadas, circuit breaking hacia un upstream que falla.
• Seguridad — terminación TLS, validación de API keys, introspección de tokens OAuth 2.0 o verificación de firmas JWT, TLS mutuo para socios, gestión de CORS, protección frente a inyecciones y validación del payload contra el esquema OpenAPI.
• Enrutamiento — enrutamiento por ruta, host y cabeceras, repartos ponderados para canary releases, upstreams versionados, reintentos y timeouts.
• Mediación — manipulación de cabeceras, adaptación de protocolos, caché de respuestas, compresión.
• Observabilidad — logs de acceso, métricas de latencia y errores por operación y por consumidor, propagación de trazas, inyección de identificadores de correlación.

# Declarative gateway configuration: one route, several policies.
routes:
  - name: payments-v2
    match:
      host: api.example.com
      path: /v2/payments
    upstream: payments-service.internal:8080
    policies:
      - jwt:
          issuer: "https://login.example.com/"
          audiences: ["payments"]
          requiredScopes: ["payments:write"]
      - rateLimit:
          identifier: consumerId        # per API consumer, not per IP
          limit: 100
          window: 1m
          policy: sliding-window
      - requestSizeLimit: { maxBodyBytes: 65536 }
      - timeout: { upstream: 2s }
      - headers:
          remove: ["X-Internal-Debug"]
          add:    { "X-Correlation-Id": "${trace_id}" }

Guarda esta configuración en control de versiones y despliégala con el mismo pipeline que el código. Un gateway configurado a base de clics en una consola es un sistema de producción sin historial, sin revisión y sin rollback.

El rate limiting en la práctica

El rate limiting protege al upstream de la sobrecarga y protege a los consumidores unos de otros. Cuatro algoritmos cubren casi cualquier despliegue, y sus diferencias aparecen justo cuando el tráfico llega a ráfagas.

Ventana fija. Se cuentan las peticiones por minuto de reloj y el contador se reinicia al cambiar de ventana. Trivial de implementar y barata de almacenar, con un defecto serio: un cliente puede enviar toda su asignación en el último segundo de una ventana y otra vez en el primer segundo de la siguiente, lo que duplica la tasa prevista a caballo entre ambas.

Ventana deslizante. Se aproximan los últimos 60 segundos ponderando la ventana fija actual y la anterior, o se guarda un registro de marcas de tiempo para ser exactos. Elimina la ráfaga del cambio de ventana con un coste adicional modesto, y es la opción por defecto sensata.

Token bucket. Un cubo contiene hasta B tokens y se rellena a R tokens por segundo; cada petición consume uno, y una petición que no encuentra token disponible se rechaza. Esto permite ráfagas de hasta el tamaño del cubo a la vez que impone una tasa media, lo que encaja con el comportamiento real de los clientes: una carga de página que lanza ocho peticiones en paralelo no debería penalizarse si el cliente, por lo demás, está tranquilo.

Leaky bucket. Las peticiones se encolan y salen a un ritmo constante, lo que suaviza por completo la salida. Útil delante de algo que de verdad no puede absorber ráfagas, como un backend legacy o la API de un socio con un límite estricto, a costa de añadir latencia a las peticiones encoladas.

Tres detalles deciden si la limitación ayuda o exaspera. Primero, qué usas como clave: limitar por dirección IP castiga a todos los que están detrás del NAT de una empresa y no hace nada contra un cliente distribuido, así que usa como clave el consumidor autenticado siempre que exista y recurre a la IP solo para el tráfico anónimo. Segundo, qué devuelves: un 429 con Retry-After y cabeceras que informen del límite, lo que queda y el momento del reinicio permite que un cliente bien educado aplique el backoff correctamente; un 429 a secas le enseña a reintentar de inmediato. Tercero, el estado compartido: en un gateway en clúster, los contadores deben compartirse o el límite efectivo se multiplica por el número de nodos.

Identidad, claves y credenciales

Conviven tres mecanismos, y cada uno responde a una pregunta distinta.

Las API keys identifican a la aplicación que llama. Son un secreto compartido en una cabecera, fáciles de emitir y fáciles de filtrar, y no llevan identidad de usuario ni caducidad a menos que se la añadas. Siguen siendo adecuadas para integraciones de servidor a servidor, para datos públicos de solo lectura y para medir el uso, siempre que solo se transmitan por TLS, se almacenen como hash, se limiten a APIs concretas y puedan rotarse sin cortes de servicio, lo que implica admitir dos claves activas por consumidor durante una rotación.

Los access tokens de OAuth 2.0 transportan una autorización delegada: qué aplicación, actuando en nombre de qué usuario, con qué scopes y hasta cuándo. El gateway valida el token —firma, emisor, audiencia, caducidad— y pasa las claims verificadas aguas abajo, de modo que los servicios nunca manejan credenciales en bruto. Es la opción por defecto correcta para todo lo que implique usuarios finales.

El TLS mutuo autentica al cliente mediante un certificado en la capa de transporte, y es habitual en integraciones con socios y en el ámbito financiero, donde una autoridad de certificación ya decide quién puede conectarse.

El reparto que funciona: el gateway rechaza todo lo que no esté autenticado o esté mal formado y reenvía una identidad verificada; el servicio aplica la autorización, porque solo el servicio sabe si este cliente puede leer esta cuenta. Un gateway no puede tomar decisiones a nivel de registro, y fingir lo contrario crea un sistema en el que cualquiera que llegue a un servicio goza de confianza absoluta: a una ruta mal configurada de una brecha de seguridad.

No dejes nunca que las credenciales lleguen a lugares donde persisten: elimina las cabeceras de autorización de los logs de acceso y rechaza tokens o claves enviados en la query string, porque acaban en los logs de los proxies y en el historial del navegador.

Productos, planes y el portal de desarrolladores

Las plataformas de gestión añaden una capa de abstracción por encima de las rutas técnicas, y es la parte que permite que un programa de APIs escale a nivel organizativo.

Un producto de API agrupa una o varias APIs en algo a lo que un consumidor se suscribe: «Payments» podría incluir la API de pagos, la API de mandatos y el feed de webhooks. Un plan asocia condiciones al producto: límites de peticiones, cuotas mensuales, endpoints disponibles, nivel de soporte y precio. Los consumidores registran una aplicación, la suscriben a un plan y reciben credenciales con el alcance correspondiente.

Esa estructura te da el vocabulario para ofrecer acceso diferenciado —un nivel gratuito de 1000 llamadas al mes para evaluación, un nivel estándar para producción, un nivel para socios con límites más altos y un contrato de soporte— sin que nada de ello aparezca en el código de los servicios.

El portal de desarrolladores es la puerta de entrada de autoservicio: catálogo de productos, referencia OpenAPI interactiva, guías de inicio, gestión de credenciales, solicitudes de suscripción, paneles de uso y changelogs. Su valor se mide por el tiempo hasta la primera llamada con éxito. Un portal en el que un desarrollador nuevo puede registrarse, obtener una clave de sandbox y recibir una respuesta real en diez minutos elimina una enorme cantidad de trabajo de soporte; uno en el que cada credencial requiere un ticket no elimina nada. Aquí, los entornos de sandbox con datos de prueba realistas importan más que cualquier funcionalidad del gateway.

La analítica cierra el círculo: llamadas por operación, por consumidor y por versión; tasas de error y sus causas; percentiles de latencia en el borde; consumo de cuota cerca de los límites. Así descubres que la versión 1 todavía soporta el 40 % del tráfico, procedente de dos consumidores, que es justo la evidencia que necesita una decisión de retirada. También es, cuando procede, la base de la facturación por uso.

La gobernanza del ciclo de vida lo une todo: revisión del diseño frente a los estándares antes de publicar, un proceso de deprecación documentado con la cabecera Sunset y avisos en el portal, y un linter que aplica tus guías de API en cada cambio de OpenAPI. Las comprobaciones automáticas en el pipeline escalan; los comités de revisión, no.

Topologías de despliegue

Dónde se ejecuta el gateway determina la latencia, el radio de impacto de un fallo y quién puede cambiarlo.

Gateway de borde centralizado. Un único clúster delante de todo. Es lo más sencillo de operar y de entender, con políticas uniformes y un solo sitio donde mirar. También es un punto único de fallo y un recurso compartido ante el que todos los equipos hacen cola, así que necesita una planificación de capacidad seria y una vía de configuración en autoservicio.

Gateway por dominio o por zona. Gateways separados para el tráfico público, de socios e interno, o por dominio de negocio. Aísla el radio de impacto, permite posturas de política distintas —el tráfico interno rara vez necesita el mismo throttling que el público— y acerca la propiedad de la configuración a los equipos.

Micro-gateway o sidecar. Un gateway ligero desplegado junto a cada servicio o equipo y configurado de forma centralizada. Elimina el cuello de botella compartido y añade los problemas de consistencia que trae un salto más; útil en organizaciones grandes a las que se les ha quedado pequeño un único borde.

Gateway cloud gestionado. El servicio propio del proveedor cloud, integrado con su gestión de identidades, logs y certificados. El menor trabajo operativo y la menor portabilidad, y normalmente se cobra por millón de llamadas, lo que pesa de verdad con grandes volúmenes.

Un modelo híbrido es habitual y razonable: un gateway gestionado para el tráfico público y un ingress controller dentro del clúster para el enrutamiento norte–sur interno. Lo que importa es que cada gateway tenga un responsable, un pipeline de configuración y un comportamiento ante fallos documentado; en concreto, si al caerse el gateway el tráfico sigue pasando (fail open) o se corta (fail closed), algo que hay que decidir deliberadamente y no descubrir sobre la marcha.

Elegir una categoría de producto

El mercado se divide en grupos reconocibles, e identificar cuál necesitas ahorra mucho esfuerzo de evaluación.

• Open source basado en proxy — un data plane rápido con un modelo de plugins, autoalojado, con funciones de gestión disponibles como complementos o en una versión de pago. Buena opción si tienes ingenieros de plataforma y quieres controlar el coste y la ubicación.
• Suites de gestión del ciclo de vida completo — gateway, portal, analítica, monetización y gobernanza en un único producto, a menudo con licencia enterprise. Se justifican cuando tienes muchos consumidores externos, condiciones comerciales y obligaciones de auditoría.
• Gateways de proveedores cloud — muy integrados, rápidos de poner en marcha, con precio por llamada, y los más flojos en portabilidad y en sofisticación del portal.
• Ingress controllers y la Kubernetes Gateway API — gestión de rutas expresada como recursos de Kubernetes. Excelentes para el enrutamiento interno y cada vez más capaces en el borde; no son una plataforma de API management.

Evalúa frente a requisitos que puedas demostrar, no frente a matrices de funcionalidades. Las preguntas que marcan la diferencia: cómo se versiona la configuración y cómo se promueve entre entornos; cuánta latencia se añade en tu p99 con tu perfil de tráfico; cómo se comparten los contadores de rate limiting entre nodos; qué le pasa al tráfico cuando el control plane está caído; si el portal admite tu propia marca y si la documentación puede publicarse automáticamente a partir de tus documentos OpenAPI; y cuánto cuesta con diez veces el volumen actual. Diseña bien la API primero —consulta diseño de APIs REST—, porque ningún gateway compensa un contrato que los consumidores no pueden usar.

Ideas clave

• Un gateway es el primer componente del recorrido que entiende de consumidores, operaciones y planes; los balanceadores y los proxies no, y un mesh resuelve la mitad interna del problema.
• Mantén el gateway fino: las políticas, el enrutamiento y la mediación van ahí; la lógica de negocio no, o acabarás reconstruyendo el enterprise service bus.
• Elige el algoritmo de rate limiting según el perfil del tráfico, usa como clave el consumidor autenticado en lugar de la dirección IP y devuelve 429 con Retry-After y cabeceras de límite.
• Deja que el gateway autentique y que el servicio autorice; un gateway no puede tomar decisiones de acceso a nivel de registro.
• Los productos, los planes y un portal de autoservicio con sandbox son lo que permite que un programa de APIs escale más allá de unos pocos consumidores, y la analítica por versión es lo que hace defendibles las decisiones de retirada.
• Elige la topología y la categoría de producto a partir de requisitos demostrables: configuración como código, latencia añadida, contadores compartidos, comportamiento ante la caída del control plane y coste a escala.