Repasa lo que escribimos en el módulo 4: un limitador de peticiones con Redis, la validación de tokens JWT y de tokens OAuth por JWKS, una lista blanca de orígenes para CORS, cabeceras de caché con ETag y 304, compresión, métricas en /metricas. Seis piezas de infraestructura, con su código, sus pruebas y su mantenimiento.

Ahora la incomodidad: casi todas existen resueltas una capa por encima. Un API gateway hace las seis, con configuración en lugar de código, y las hace para todas tus APIs a la vez. La pregunta obvia es si perdimos el tiempo. La respuesta es que no —entender un mecanismo es lo que permite decidir si delegarlo y depurarlo cuando falle—, pero la pregunta siguiente sí es difícil y es la que ocupa media lección: qué se delega en el gateway y qué debe quedarse en la aplicación.

Y hay una segunda mitad. Tenemos una API excelente, documentada y desplegada. Pero CataBox, la aplicación de terceros que se integra por OAuth, no tiene ni idea de cómo empezar: dónde registrarse, cómo conseguir credenciales, dónde probar sin romper nada, qué límites tiene, cuándo cambiará algo. Eso es un portal de desarrollador, y determina si tu API se usa o se abandona en la primera hora.

Esta lección cierra el módulo 5 con las dos capas que rodean a la API: la que la protege y la que la explica.

1. Qué es un API gateway y qué problema resuelve
2. Las funciones que asume, comparadas con el módulo 4
3. Qué delegar y qué no delegar nunca
4. La arquitectura completa: CDN, gateway, servicios
5. El patrón backend for frontend
6. El service mesh es otra cosa
7. Los productos y cómo se comparan
8. Configuración de Kong para Tienda Aroma
9. La alternativa con NGINX
10. Qué middlewares podríamos retirar y cuáles no
11. Los riesgos del gateway
12. Qué es un portal de desarrollador
13. Qué contiene un buen portal
14. Registro de aplicaciones y credenciales OAuth
15. El tiempo hasta la primera llamada con éxito
16. Ciclo de vida e inventario de APIs
17. Monetización, como nota
18. Balance del módulo 5

Un API gateway es un servidor que se sitúa delante de una o varias APIs y actúa como puerta única: recibe todo el tráfico externo, aplica políticas transversales y reenvía las peticiones al servicio que corresponda.

El problema que resuelve se ve mejor con el escenario que le da sentido. Imagina que Tienda Aroma crece:

Con una API, el gateway aporta poco: estás moviendo de sitio código que ya funciona. Con cinco, la diferencia es enorme: sin él, cada equipo reimplementa el rate limiting a su manera, tres de los cinco lo hacen mal, la política de CORS diverge, y no hay un sitio donde responder «¿cuántas peticiones recibimos en total?».

La formulación precisa: un gateway centraliza las preocupaciones transversales del tráfico. Y como todo lo centralizado, aporta consistencia y crea un punto único de fallo. Ambas cosas a la vez.

Las tres últimas filas son el asunto del apartado siguiente.

El criterio, en una frase: el gateway sabe quién llama y a dónde; solo la aplicación sabe qué hay dentro y qué significa.

De ahí se deduce todo lo demás:

Se delega bien lo que depende únicamente de la petición y de la identidad: rate limiting, terminación TLS, verificación criptográfica del token, CORS, compresión, enrutado. Son decisiones que no requieren consultar tu base de datos.

No se delega nunca, y conviene ser tajante:

1. La autorización a nivel de recurso. El gateway puede comprobar que el token es válido y que tiene el ámbito pedidos.leer. No puede comprobar que ped_5001 pertenece a cli_842, porque eso exige consultar la base de datos. Y esa comprobación es precisamente la que evita el fallo número uno del OWASP API Top 10 (04-02), el BOLA. Si dejas de hacerla en la aplicación porque "ya lo mira el gateway", tienes una vulnerabilidad crítica.

2. La lógica de negocio. Que un pedido pagado no pueda volver a pendiente_pago, que no se venda más stock del disponible, que el plazo de devolución sean 14 días. Meter reglas de negocio en la configuración del gateway crea un segundo lugar donde vive el dominio, sin pruebas, sin tipos y sin revisión de código. Es el error más caro que se comete con estas herramientas.

3. La validación semántica. El gateway puede rechazar un cuerpo que no cumpla el JSON Schema —tipos, rangos, campos obligatorios— y es una defensa útil. No puede validar que cafeId exista, que precioMin sea menor que precioMax, o que el cliente pueda comprar ese café.

4. La defensa en profundidad. Aunque el gateway valide el token, la aplicación debe seguir validándolo. Motivo: si alguien alcanza tu servicio esquivando el gateway —una regla de red mal puesta, un despliegue nuevo, un atacante dentro de la red— tu API quedaría totalmente abierta. La regla es zero trust: el servicio no confía en que el tráfico venga de donde parece.

Una tabla que resume la asignación:

Qué hace cada capa y por qué está donde está:

Las flechas punteadas del diagrama son importantes: el tráfico norte-sur (de fuera hacia dentro) pasa por el gateway; el tráfico este-oeste (entre servicios internos) no. Hacer que las llamadas internas salgan y vuelvan a entrar por el gateway multiplica la latencia y convierte el gateway en el cuello de botella de todo el sistema.

Aroma Móvil tiene un problema que la SPA no tiene: para pintar la pantalla de inicio necesita el catálogo destacado, los pedidos recientes del cliente y sus preferencias. Con la API tal cual, son tres peticiones, sobre una red móvil con 150 ms de latencia y una batería que se gasta.

Un BFF es una API intermedia dedicada a un consumidor concreto, que agrega y adapta:

La ventaja política del BFF es tan importante como la técnica: el equipo móvil puede cambiar su BFF sin negociar con nadie ni esperar un ciclo de versionado, porque es el único consumidor. La trampa es que un BFF acabe con reglas de negocio propias que divergen de la API. Regla: el BFF agrega, filtra y adapta formatos; no decide nada del dominio.

Algunos gateways ofrecen agregación por configuración, sin escribir un BFF. Funciona para casos triviales y se vuelve inmanejable en cuanto hay lógica condicional. Si necesitas un if, escribe un BFF.

Se confunden constantemente, así que conviene separarlos:

No son alternativas: son complementarios, y muchas arquitecturas maduras tienen ambos. Para Tienda Aroma hoy, con una API y dos servicios internos, un service mesh es claramente prematuro: su coste operativo solo se amortiza con decenas de servicios.

Criterios de elección, que se parecen mucho a los de 05-03:

• ¿Quién lo va a operar? Un Kong autogestionado en alta disponibilidad es un sistema distribuido más que mantener, parchear y monitorizar. Si el equipo es pequeño, la opción gestionada casi siempre gana.
• ¿Dónde está el resto? Si ya estás en AWS con ECS, AWS API Gateway ahorra integración. Si ya usas Cloudflare, buena parte del trabajo puede hacerse ahí.
• ¿Necesitas un portal? Si vas a tener terceros como CataBox, el portal es la mitad del producto. Kong OSS no lo trae; Tyk sí; Apigee y Azure APIM traen los más completos.
• ¿Cuánto cuesta por petición? Los gestionados cobran por millón de peticiones. Con volúmenes altos, la cuenta puede superar al coste de operarlo tú.
• ¿Qué modelo de configuración? La configuración declarativa en YAML versionada en Git (Kong con decK, Traefik, Gateway API de Kubernetes) es muy superior a configurar por interfaz gráfica: se revisa en un pull request y se despliega con la tubería de 05-05.

Configuración declarativa completa, versionable en el repositorio como gateway/kong.yaml:

Cuatro puntos de esa configuración que merecen comentario:

• fault_tolerant distinto según la ruta. En el límite global es true: si Redis cae, preferimos dejar pasar tráfico a tirar la API entera. En el login es false: si Redis cae, preferimos bloquear a quedarnos sin protección contra fuerza bruta. Es una decisión de disponibilidad frente a seguridad que debe tomarse conscientemente para cada caso, y el gateway obliga a explicitarla.
• limit_by: consumer frente a limit_by: ip. Limitar por IP castiga a todos los usuarios detrás de un NAT corporativo y no protege de un atacante con muchas IP. Por consumidor autenticado es lo correcto… salvo en el login, donde todavía no hay consumidor.
• exposed_headers. El error de CORS más frustrante de 04-05: el navegador recibe ETag pero JavaScript no puede leerlo si no está en Access-Control-Expose-Headers. Aquí queda declarado de una vez para toda la API.
• preflight_continue: false. El gateway responde los OPTIONS y la aplicación no los ve. Ahorra latencia y una parte del tráfico, pero significa que tu middleware de CORS deja de ejecutarse para el preflight: si algún día quitas el gateway, recuerda que esa pieza estaba ahí.

La configuración se aplica desde la tubería de 05-05:

Esto es infraestructura como código aplicada al gateway, y es lo que evita el problema clásico: alguien toca la configuración en la interfaz gráfica un martes, nadie lo recuerda, y en la siguiente reconstrucción del entorno la política desaparece.

Si el equipo ya opera NGINX y no necesita gestión de consumidores ni portal, buena parte de lo anterior se consigue con configuración directa:

La cabecera X-Forwarded-For conecta directamente con el trust proxy 1 de la posición 1 de src/app.js. Sin X-Forwarded-For, Express ve la IP del gateway en todas las peticiones y el rate limiting por IP limita al gateway entero. Y con trust proxy mal configurado —confiando en más saltos de los que hay— un atacante puede falsificar su IP añadiendo la cabecera él mismo. El número debe coincidir exactamente con la cantidad de proxies de confianza que hay delante.

Lo que NGINX no da y Kong sí: gestión de consumidores con credenciales, cuotas mensuales, validación de JWT sin recurrir a Lua, portal de desarrollador y configuración por API en lugar de por fichero. Para una API con socios y terceros, esas ausencias pesan.

La pregunta práctica: con el gateway de arriba delante, ¿qué queda en src/app.js?

Balance honesto: se retiran uno o dos middlewares de dieciséis. Ese es el resultado real y conviene decirlo sin adornos, porque contradice la promesa comercial de estas herramientas.

El valor del gateway no está en adelgazar tu aplicación. Está en tres cosas distintas:

1. Consistencia entre varios servicios. Con cinco APIs, las políticas se escriben una vez en lugar de cinco.
2. Gestión de consumidores. Cuotas por plan, credenciales, mTLS con socios, listas negras. Eso no existía en nuestro proyecto y construirlo sería costoso.
3. Cambiar políticas sin desplegar. Ajustar un límite o bloquear a un cliente abusivo es una línea de YAML y treinta segundos, en lugar de un despliegue completo.

Y una última observación importante: la configuración del gateway hay que probarla igual que el código. El recorrido de Newman de 05-01 debe ejecutarse contra el gateway, no contra la API directamente. Si no, un CORS mal configurado o un strip_path equivocado se descubre en producción. Con deck gateway diff en el pull request, el cambio de política se revisa como cualquier otro.

1. Punto único de fallo. Si el gateway cae, todas tus APIs caen a la vez, aunque estén perfectamente sanas. Mitigación: varias instancias, comprobaciones de salud, y —lo que casi nadie hace— un plan documentado para exponer temporalmente los servicios sin él.

2. Cuello de botella y latencia añadida. Cada petición atraviesa un salto de red y un procesamiento adicional: entre 1 y 10 ms típicamente. Con un presupuesto de latencia de 200 ms (04-06) es asumible; si tu p99 objetivo son 20 ms, es un 25 % del presupuesto y hay que medirlo, no suponerlo.

3. Configuración duplicada y divergente. El caso más pernicioso: CORS configurado en el gateway y en la aplicación con listas distintas. Un origen funciona en desarrollo y falla en producción, o al revés, y depurarlo es un infierno porque cada capa dice que está bien. Regla: una política, un dueño, documentado en un ADR (04-01).

4. Lógica de negocio en el gateway. El riesgo más caro. Empieza con una transformación inocente y acaba con reglas de precios en un script Lua sin pruebas, sin control de versiones efectivo y sin nadie que sepa que están ahí. La regla del apartado 3 no admite excepciones.

5. Dependencia del proveedor. Las políticas de Apigee o de Azure APIM no se migran a Kong. Cuanto más lógica metas en el gateway, más caro es cambiarlo. Otro argumento para mantenerlo fino.

6. Falsa sensación de seguridad. «El gateway valida los tokens, así que la app puede confiar.» No. Zero trust: la aplicación valida siempre.

7. Depuración más difícil. Un 403 puede venir del gateway o de la aplicación, y a veces no es evidente cuál. Mitigación: que el gateway marque sus propios errores —una cabecera propia, o un campo en detalles— y que el Aroma-Traza-Id atraviese ambas capas, que es exactamente para lo que sirve el plugin correlation-id.

Cambiamos de tema y de audiencia. Un portal de desarrollador es el sitio web donde quien quiere integrarse con tu API aprende a hacerlo, se registra, obtiene credenciales, prueba y se entera de los cambios.

La pregunta que responde: CataBox quiere integrarse con Tienda Aroma un martes por la mañana. ¿Qué pasa?

Quién lo necesita: cualquier API con consumidores que no estén en tu equipo. Con una API estrictamente interna y dos equipos, /docs con Swagger UI y un canal de chat pueden bastar. En cuanto hay terceros, socios o más de cuatro o cinco equipos internos, el portal deja de ser un lujo.

Tres apartados suelen faltar y son los que más se agradecen:

• Guías temáticas, no solo referencia. La referencia dice que POST /v1/pedidos acepta Idempotency-Key. Una guía explica por qué, qué pasa al reintentar, cuánto tiempo se conserva la clave y cómo generarla. La referencia responde "qué"; la guía responde "cómo y por qué", y es lo que evita las integraciones mal hechas.
• La página de errores. El catálogo completo de 02-04 con qué significa cada código, si conviene reintentar y qué hacer. Con 429 y Retry-After, con 409 de idempotencia, con 412 de If-Match. Es la página que más visitas recibe de un portal maduro, y su ausencia se traduce directamente en tickets de soporte.
• Ejemplos ejecutables. curl copiable, y la colección de Postman de 05-01 con un botón de importar. Que alguien pueda pegar un comando y ver una respuesta real en treinta segundos vale más que diez páginas de prosa.

Y una guía de inicio que funciona tiene esta forma, sin adornos:

Cuatro pasos, tres minutos, cero ambigüedad. Ese es el estándar.

El flujo por el que un tercero se convierte en consumidor:

Decisiones de diseño de este flujo, todas con consecuencias de seguridad (04-02 y 04-03):

• El client_secret se muestra una sola vez. Se guarda como hash, igual que una contraseña. Si se pierde, se rota; no se recupera.
• Aplicaciones públicas frente a confidenciales. Una SPA o una app móvil no pueden guardar un secreto: son públicas y deben usar Authorization Code con PKCE. El portal debe preguntar el tipo y no ofrecer secreto a las públicas.
• Ámbitos mínimos. Que CataBox pida cafes.leer y resenas.escribir, no todos. El portal debe explicar qué permite cada ámbito con lenguaje claro, porque ese texto es el que verá el cliente final en la pantalla de consentimiento.
• Ámbitos sensibles con revisión manual. resenas.moderar o envios.escribir no se conceden automáticamente: se solicitan y alguien los aprueba.
• Aprobación separada para producción. El entorno de pruebas es inmediato; el acceso a producción exige revisar la aplicación. Es lo que evita que un desarrollador curioso llegue a datos reales.
• Rotación de credenciales sin corte: poder tener dos secretos válidos a la vez durante la rotación. Sin eso, rotar implica un corte, y la consecuencia es que nadie rota nunca.

Hay una métrica que resume la calidad de la experiencia de integración: TTFHW (time to first hello world), el tiempo desde que alguien llega a tu portal hasta que recibe su primera respuesta 200.

Por qué importa tanto: en los primeros minutos, quien evalúa tu API decide si sigue o busca otra cosa. Un TTFHW de treinta minutos con tres correos a soporte por medio es una barrera comercial real, no un detalle de experiencia de usuario.

Cómo se mide de verdad: siéntate con alguien que no conozca la API, dale el enlace del portal y cronometra sin ayudarle. Anota cada punto donde duda, se equivoca o se para. Esos puntos son la lista de tareas, ordenada por impacto. Es una prueba que cuesta una hora y produce mejor información que cualquier encuesta.

Los frenos habituales, que se repiten en casi todas las APIs:

1. El registro pide datos innecesarios en el primer paso (razón social, teléfono, dirección fiscal).
2. Las credenciales requieren aprobación humana incluso para el entorno de pruebas.
3. El ejemplo de la documentación no funciona copiado y pegado (falta una cabecera, la URL está desactualizada).
4. El entorno de pruebas no tiene datos: el primer GET devuelve una lista vacía y parece que algo falla.
5. Los errores no explican el problema: un 401 genérico sin decir si el token es inválido, ha caducado o le falta el ámbito.

El punto 4 es especialmente traicionero. El entorno de pruebas debe estar sembrado con datos ficticios ricos: nuestro npm run sembrar con caf_001, caf_002, cli_842 y ped_5001 cumple exactamente esa función, y por eso las primeras llamadas del portal devuelven algo interesante en lugar de {"datos": [], "total": 0}.

En 04-02, el noveno punto del OWASP API Top 10 era la gestión inadecuada del inventario: APIs olvidadas, versiones antiguas aún vivas, endpoints de pruebas expuestos. Aquí es donde se resuelve.

El gateway es la fuente de verdad del inventario, porque todo lo que se expone pasa por él. Si algo recibe tráfico externo y no está en la configuración del gateway, es una API en la sombra y hay un problema.

Cada API o versión tiene un ciclo de vida explícito:

La última fila es el problema real. Las APIs zombis aparecen porque nadie tiene la lista completa, y sobreviven porque nadie se atreve a apagar algo por si acaso.

Las prácticas que lo evitan, todas apoyadas en piezas que ya tenemos:

• Inventario automático desde la configuración del gateway, versionada en Git.
• Métricas de uso por ruta, versión y consumidor (04-07 y el plugin prometheus con per_consumer). Antes de retirar /v1 la pregunta «¿quién la usa todavía?» tiene una respuesta con nombres y volúmenes, no una suposición.
• Un dueño por API, con nombre y equipo. Sin dueño, no hay quien decida.
• Fecha de revisión. Cada API se revisa al menos una vez al año: ¿sigue haciendo falta?, ¿está documentada?, ¿tiene consumidores?
• Los entornos de no producción, cerrados. Preproducción sin autenticación, accesible desde internet, es un clásico y aparece en los informes de brechas con frecuencia deprimente.
• La retirada, en dos fases. Primero el apagado de prueba: devolver 410 durante unas horas en una fecha anunciada. Los consumidores que quedaban aparecen inmediatamente. Después, la retirada definitiva. Es mucho más eficaz que cualquier correo de aviso.

Cuando la API es en sí misma un producto, el gateway y el portal aportan la infraestructura de cobro. Los modelos habituales:

Las piezas técnicas están todas en esta lección: cuotas en el gateway por consumidor, medición con las métricas por consumidor, planes en el portal, y la facturación integrada con la pasarela.

Un aviso sobre la medición, que es donde se cometen los errores caros: hay que decidir explícitamente si se cobran las llamadas fallidas. Cobrar un 500 propio es indefendible; no cobrar un 429 puede incentivar el abuso. Y la medición debe ser auditable: un cliente tiene derecho a ver su consumo desglosado y a cuadrarlo con su factura.

Para Tienda Aroma, la API no es el producto: es el canal. Un reparto de ingresos con CataBox por pedidos referidos tendría más sentido que cobrar por llamada.

• Poner un gateway teniendo una sola API. Añades un punto de fallo, latencia y una herramienta más que operar, a cambio de casi nada. El gateway se justifica con varios servicios o con terceros que gestionar.
• Quitar la autenticación de la aplicación porque el gateway la hace. Si alguien alcanza el servicio esquivando el gateway, tu API está completamente abierta. Zero trust, siempre.
• Delegar la autorización a nivel de recurso. El gateway no puede saber que ped_5001 es de cli_842. Es el fallo número uno del OWASP API Top 10 y no tiene solución fuera de la aplicación.
• Meter lógica de negocio en el gateway. Reglas de dominio en un script Lua sin pruebas, sin tipos y sin revisión. Es el error más caro de revertir.
• Configurar CORS en el gateway y en la aplicación con listas distintas. Un origen funciona en un entorno y falla en otro, y depurarlo lleva horas porque cada capa parece correcta. Una política, un dueño.
• Olvidar exposed_headers en el gateway. El navegador recibe ETag y Link pero JavaScript no puede leerlos. Es el error de CORS más frustrante de 04-05.
• trust proxy mal configurado. Con menos saltos de los que hay, la IP real se pierde; con más, un atacante puede falsificarla. El número debe coincidir exactamente.
• Configurar el gateway por interfaz gráfica. Nadie recuerda qué se cambió ni por qué, y se pierde en la siguiente reconstrucción. Configuración declarativa versionada y aplicada desde la tubería.
• No probar contra el gateway. El recorrido de Newman de 05-01 debe apuntar al gateway. Un strip_path equivocado o un CORS mal puesto se descubren en producción si no.
• Un portal que es solo Swagger UI. La referencia sin guía de inicio, sin página de errores y sin ejemplos ejecutables deja a quien se integra buscando dónde empezar.
• Aprobación manual para el entorno de pruebas. Multiplica el TTFHW por cien y hace que la gente pruebe la API de la competencia mientras espera.
• Un entorno de pruebas vacío. La primera llamada devuelve {"datos": [], "total": 0} y parece rota. Siémbralo con datos ficticios ricos.
• Consejo: mide el TTFHW con una persona real y un cronómetro. Una hora de observación produce mejor información que cualquier encuesta.
• Consejo: antes de retirar una versión, haz un apagado de prueba. Unas horas de 410 en una fecha anunciada descubren a todos los consumidores que quedaban, cosa que ningún correo de aviso consigue.
• Consejo: documenta en un ADR (04-01) qué política vive en el gateway y cuál en la aplicación. Es la información que falta el día del incidente.

Tienda Aroma va a poner Kong delante de la API. Para cada requisito, decide si se implementa en el gateway, en la aplicación o en ambos, y justifícalo:

1. Rechazar peticiones sin token válido.
2. Comprobar que un cliente solo ve sus propios pedidos.
3. Limitar a CataBox a 10.000 llamadas al mes.
4. Rechazar precioMin mayor que precioMax.
5. Bloquear un rango de IP que está atacando el login.
6. Devolver 409 pedido_ya_pagado si el pedido ya se pagó.
7. Permitir peticiones desde https://panel.tiendaaroma.example y de ningún otro origen.
8. Exigir la cabecera Idempotency-Key en POST /v1/pedidos.
9. Rechazar cuerpos mayores de 100 KB.
10. Devolver 304 cuando el ETag coincide con If-None-Match.

Tienda Aroma publica /v2, que vive en un servicio separado (api-v2.interno:3000), mientras /v1 sigue en el servicio actual con seis meses de convivencia. Escribe la configuración declarativa de Kong necesaria: los servicios y rutas, cómo se aplican los mismos plugins de rate limiting y CORS a ambas versiones sin duplicar configuración, y cómo se añaden las cabeceras Deprecation, Sunset y Link con la sucesora solo a las respuestas de /v1. Indica también qué pasa el día del Sunset.

Un portal de la competencia tiene: página de inicio con la propuesta de valor, referencia completa generada de OpenAPI con consola "probar ahora", formulario de contacto para solicitar acceso —respuesta en 2-3 días laborables—, PDF con los planes y precios, y una página de estado del servicio.

Identifica al menos cinco carencias graves, estima el TTFHW resultante justificando la estimación, y propón un plan priorizado de mejora con las tres primeras acciones, indicando qué métrica esperarías mover con cada una.

Patrón que emerge: todo lo que depende del contenido o del estado persistido se queda en la aplicación; todo lo que depende de quién llama y cuánto llama va al gateway; y lo que es barato comprobar dos veces se hace en ambos.

Cómo se evita la duplicación: los plugins declarados en el nivel superior (sin service ni route) son globales y se aplican a todas las rutas. Solo se declara por servicio o por ruta lo que difiere, que aquí es únicamente el response-transformer con las cabeceras de deprecación. Cambiar el límite global es una línea que afecta a ambas versiones.

Detalle que se olvida siempre: Deprecation y Sunset deben estar en exposed_headers del plugin de CORS. Si no, el navegador las recibe pero la SPA no puede leerlas, y la instrumentación que querías —que el front avise en consola de que usa una versión obsoleta— no funciona.

Qué pasa el día del Sunset (30 de junio de 2027):

Secuencia recomendada:

1. Meses antes: cabeceras Deprecation y Sunset activas (ya lo están), avisos en el changelog del portal, y correos a los consumidores identificados por las métricas del gateway, que dicen exactamente quién sigue llamando a /v1 y con qué volumen.
2. Un mes antes: apagado de prueba de dos horas, anunciado. Aparecen los rezagados.
3. El día del Sunset: se activa el request-termination con 410. 410 Gone y no 404, porque 410 significa "existió y se retiró deliberadamente", que es información útil para quien depura.
4. Semanas después: se elimina la ruta de la configuración y se apaga el servicio api-v1. El 410 deja paso al 404 genérico.

Se mantiene el 410 explicativo durante semanas en lugar de borrar la ruta de inmediato porque un 404 seco deja al consumidor sin saber qué pasó, mientras que el 410 con enlace a la guía de migración es autoexplicativo.

Cinco carencias graves:

1. Acceso con aprobación manual de 2-3 días. Es la carencia más grave con diferencia. Convierte una evaluación de cinco minutos en un proyecto de una semana, y quien evalúa alternativas probará la de la competencia mientras espera. Muchos nunca vuelven.
2. No hay entorno de pruebas con credenciales inmediatas. Consecuencia de la anterior: no se puede tocar nada sin permiso, así que la consola "probar ahora" es decorativa. Nadie puede evaluar la API sin comprometerse antes.
3. Solo hay referencia, no guías. La referencia dice qué campos acepta POST /pedidos; no explica la idempotencia, la paginación, cómo reintentar ante un 429 o cómo verificar la firma de un webhook. Sin eso, todas las integraciones se hacen mal de la misma manera y el coste se traslada a soporte.
4. Precios en un PDF. Un PDF no se puede enlazar a una sección concreta, se desactualiza sin que nadie lo note, no es accesible y transmite que la información es estática. Además, si los planes están en PDF, las cuotas técnicas probablemente no estén documentadas en ninguna parte.
5. No hay changelog ni política de deprecación. Es la carencia que más miedo da a quien va a construir un negocio encima: no hay forma de saber si la API cambiará ni con cuánto aviso. Sin un compromiso público de compatibilidad, integrarse es asumir un riesgo indefinido.

Carencias adicionales: no hay página de errores con el catálogo de códigos; no se ve una colección de Postman ni ejemplos ejecutables; nada indica los límites de uso técnicos; y no hay clientes generados ni SDK (05-02).

Estimación del TTFHW: 2-3 días laborables. El desglose justifica la cifra: descubrimiento y lectura, 10 minutos; rellenar el formulario, 5 minutos; espera de aprobación, 2-3 días; configurar la autenticación con documentación incompleta, 30-60 minutos; primera llamada con éxito, 10 minutos. El tiempo activo son unos 90 minutos; el tiempo transcurrido, tres días. Y lo que cuenta comercialmente es el transcurrido, porque es el que determina si la persona sigue interesada.

Plan priorizado — tres primeras acciones:

Acción 1 (impacto altísimo, coste medio): registro automático para el entorno de pruebas. Cualquiera se registra con un correo, crea una aplicación y obtiene client_id y client_secret de pruebas al instante. La aprobación manual se conserva solo para producción, que es donde de verdad hace falta. El sandbox debe estar sembrado con datos ficticios ricos para que la primera llamada devuelva algo interesante. Métrica esperada: TTFHW de 2-3 días a menos de 15 minutos. Es un cambio de orden de magnitud y, por sí solo, justifica el proyecto.

Acción 2 (impacto alto, coste bajo): guía de inicio de cuatro pasos y página de errores. Una página con registro → token → primera llamada → siguientes pasos, con comandos curl copiables y probados en CI para que nunca se desactualicen (05-04 ya nos enseñó a probar que los ejemplos del contrato funcionan). Y una página con el catálogo completo de errores: qué significa cada código, si conviene reintentar y qué hacer. Métrica esperada: reducción del tiempo activo de 90 a 20 minutos, y caída de los tickets de soporte de primer nivel, que suelen ser el 60-70 % del total y casi siempre son "no entiendo este error".

Acción 3 (impacto medio-alto, coste bajo): changelog público y compromiso de compatibilidad. Una página con el historial de cambios, un compromiso explícito —"no eliminamos campos sin seis meses de aviso; los cambios rompedores van en una versión mayor de la ruta"— y suscripción por correo o RSS. Es la pieza que convierte una API que se prueba en una API sobre la que alguien se atreve a construir un producto. Métrica esperada: conversión de cuentas de prueba a integraciones en producción. Y, a medio plazo, menos incidencias en cada despliegue, porque los consumidores se enteran de los cambios antes de sufrirlos.

Después: publicar los precios en HTML, ofrecer la colección de Postman con un botón de importar, generar SDK con OpenAPI Generator (05-02) y documentar los límites técnicos junto a los planes.

Has visto la capa que rodea a la API por fuera. Un API gateway centraliza las preocupaciones transversales del tráfico —rate limiting, terminación TLS, validación de JWT y OAuth por JWKS, CORS, compresión, enrutado por versión, cuotas por consumidor, métricas, mTLS con socios, listas negras— y las convierte en configuración declarativa versionable en lugar de código repetido en cada servicio. Tienes su configuración real para Tienda Aroma en gateway/kong.yaml, con los mismos límites de 04-04 y su fault_tolerant decidido ruta a ruta, la lista blanca de 04-05 con los exposed_headers que casi todo el mundo olvida, el correlation-id que propaga el Aroma-Traza-Id de 04-07 y el plugin de Prometheus segmentado por consumidor; y la alternativa equivalente en gateway/nginx.conf, con el X-Forwarded-For que da sentido al trust proxy 1 de la posición 1 de src/app.js.

Y tienes el criterio, que vale más que la configuración: el gateway sabe quién llama y a dónde; solo la aplicación sabe qué hay dentro y qué significa. Por eso el rate limiting, el TLS, la validación criptográfica del token y el CORS se delegan bien, mientras que la autorización a nivel de recurso, la lógica de negocio y la validación semántica no se delegan nunca —y por eso, con el gateway delante, de los dieciséis middlewares de src/app.js solo se retiran uno o dos—. El valor no está en adelgazar tu aplicación, sino en la consistencia entre varios servicios, en la gestión de consumidores que antes no existía y en poder cambiar políticas sin desplegar. Todo ello asumiendo sus riesgos con los ojos abiertos: punto único de fallo, latencia añadida, configuración divergente y la tentación siempre presente de meter reglas de negocio donde no hay pruebas ni revisión.

La segunda mitad de la lección era la otra cara: un portal de desarrollador con guía de inicio de cuatro pasos, referencia generada del openapi.yaml de 05-02, consola interactiva, registro de aplicaciones con credenciales OAuth inmediatas para el entorno de pruebas, página de errores con el catálogo de 02-04, changelog con los avisos de deprecación de 02-07, límites, estado del servicio y soporte. Con una métrica que lo resume todo, el tiempo hasta la primera llamada con éxito, que se mide con una persona real y un cronómetro y que decide si tu API se adopta o se abandona en la primera hora. Y con la gestión del ciclo de vida y del inventario, donde el gateway se convierte en la fuente de verdad de qué está expuesto y las métricas por consumidor responden con nombres y volúmenes a la pregunta «¿quién sigue usando /v1?» antes de retirarla —con un apagado de prueba de unas horas, que descubre rezagados como no lo consigue ningún correo—.

Con esto se cierra el módulo 5. La API de Tienda Aroma ya no está sola: tiene una colección de Postman ejecutable en CI, un contrato OpenAPI completo que sirve de documentación, de mock, de validador y de generador de clientes, la perspectiva para saber qué habría cambiado con otro framework y qué no, pruebas de contrato que impiden que el código y el contrato se separen junto a una puerta que detecta cambios rompedores, una tubería que construye, prueba y despliega sin cortes con migraciones retrocompatibles y vuelta atrás, y una capa de gateway y portal que la protege y la explica. Es una API operable y consumible, no solo correcta.

Lo que falta ya no es ninguna pieza suelta: es ver todo esto junto, aplicado de principio a fin y sostenido en el tiempo. En el módulo 6, Casos de Estudio y Proyectos, dejamos las herramientas y volvemos al diseño con todo lo aprendido encima: un caso de estudio completo de la API de una tienda en línea, recorriendo las decisiones desde los recursos hasta el despliegue (06-01); un segundo caso, el de una red social, donde los problemas son distintos —grafos de relaciones, líneas de tiempo, paginación por cursor a gran escala, contenido generado por usuarios y moderación— y obligan a replantear varias de las decisiones que aquí dimos por buenas (06-02); la evolución y el mantenimiento de una API en producción, es decir, qué ocurre los tres años siguientes al lanzamiento: deuda de contrato, migraciones de versión, incidentes reales y retirada de funcionalidades (06-03); y el proyecto final, en el que diseñarás y desarrollarás tu propia API RESTful aplicando los seis módulos completos (06-04).