Resumen

  • RFC 9727 define /.well-known/api-catalog y la relación api-catalog para que un publicador declare una colección de API. No certifica propiedad, autorización, alcance, vigilancia ni salud de cada elemento.
  • Los catálogos raíz, externos y anidados tienen autoridades, contextos, cachés y calendarios distintos. La topología es un grafo de afirmaciones fechadas, no una herencia automática de confianza.
  • Eliminar un item demuestra que cambió una publicación. Una retirada segura exige además evidencia separada de exposición, tráfico, dependencias, ejecución del cambio, reversión y observación posterior.

El inventario puede cerrar antes que el puerto

RFC 9727, publicado en febrero de 2025 en el Standards Track del IETF, crea un mecanismo deliberadamente pequeño. El publicador responde en /.well-known/api-catalog, puede anunciar el catálogo mediante Link y lo entrega como Linkset JSON. item enumera API; api-catalog enlaza catálogos subordinados.

La utilidad es inmediata. En muchas organizaciones, los nombres viven repartidos entre configuraciones de despliegue, pasarelas, portales y hojas privadas. El punto común convierte una memoria fragmentada en una declaración que otras herramientas pueden leer.

Sin embargo, RFC 8288 expresa relaciones tipadas, no certificados operativos. Un item válido no demuestra que el DNS resuelva desde cierta red, que haya un listener, que el publicador opere el destino, que existan credenciales ni que termine una transacción. Una ruta no listada tampoco deja de existir.

OWASP API9:2023 relaciona versiones antiguas, hosts no documentados y entornos imprecisos con una superficie de ataque mayor. RFC 9727 reduce esa ceguera si el catálogo se contrasta con la infraestructura. Si solo se cuentan enlaces, puede convertir una lista pulcra en una nueva falsa certeza.

La autoridad se comprueba enlace por enlace

Que el catálogo esté en el dominio de la empresa no convierte todos sus destinos en activos propios. Puede incluir socios, servicios administrados, regiones o entradas históricas. La evidencia sostiene que el publicador decidió incluir la relación; propiedad y control requieren registros independientes.

RFC 9727 permite dirigir el descubrimiento a otro dominio cuando no se puede alojar el recurso well-known. La respuesta inicial, los redirects, las identidades TLS, los tiempos y el hash forman entonces una cadena de publicación. Conservar solo el resultado final borra quién remitió a quién.

Los catálogos anidados repiten el problema. Un grupo enlaza productos y los productos enlazan regiones, con equipos y calendarios distintos. RFC 9264 exige contexto explícito porque mover un Linkset sin su anchor puede cambiar su significado. No es un árbol que herede verdad, sino un grafo de afirmaciones fechadas.

Un recibo útil conservaría dominio, ruta, redirects, par TLS, hora, tipo de medio, profile, ETag o Last-Modified, hash y cada triple contexto—destino—relación. La primera y última observación no son automáticamente fechas de creación y borrado. Es una propuesta de control de este análisis, no una obligación añadida al RFC.

El catálogo y el API llevan relojes diferentes

RFC 9111 separa frescura, revalidación y uso de respuestas obsoletas. Un ETag demuestra estabilidad de la representación entre validaciones; no continuidad de los servicios listados. Una frescura larga puede retrasar una baja urgente. Una corta aumenta carga sin corregir un origen mal mantenido.

Conviene separar la hora pretendida por el publicador, la respuesta del origen, la validación o reutilización del caché, el cambio en la pasarela y la observación. «No aparecía a las 14:00» es verificable con la respuesta y el camino de caché; no equivale a «se apagó a las 14:00».

RFC 9727 recomienda medir disponibilidad y rendimiento del catálogo, correlacionar consultas con solicitudes posteriores, retirar entradas obsoletas, validar sintaxis y reglas de negocio e integrar la actualización en el ciclo de releases. También afirma que el catálogo complementa un marco de gestión de API y no lo sustituye.

La salud del catálogo no es la de sus elementos

Una sonda puede obtener el catálogo, validar el JSON y recorrer todos los niveles mientras una API responde con errores. También puede caer el catálogo y seguir funcionando un cliente que conoce la URL.

La relación status de RFC 8631 puede señalar un recurso de estado, pero no fusiona catálogo, página de estado y transacción. Conexión TCP, respuesta HTTP y operación autenticada son observaciones distintas. Toda afirmación de salud necesita transacción, punto de observación, identidad y ventana temporal.

RFC 9727 advierte además que un catálogo puede revelar API internas. TLS, revisión, mínimo privilegio de escritura, límites de tasa y control de acceso protegen la publicación, pero no demuestran que un destino no esté expuesto fuera. Poder leer la lista tampoco concede autorización de uso.

Borrar la ficha no apaga el servicio

Auditar el catálogo puede descubrir API zombis: interfaces sin soporte, vigilancia o parches. Son peligrosas porque el registro administrativo se separó del sistema en ejecución. El hallazgo abre el trabajo de retirada; no lo cierra.

Eliminar un item puede corregir, trasladar, ocultar, sustituir o preparar una retirada. No cierra listeners, revoca secretos, borra DNS, vacía colas ni actualiza clientes desconocidos. Mantenerlo tampoco acredita soporte.

Un recibo de retirada debe unir última instantánea y decisión autorizada con cambios de DNS, rutas, balanceadores y pasarelas; interfaces y entornos; propietarios y procesos dependientes; tráfico con ventana y puntos ciegos; credenciales y flujos; confirmación de ejecución; responsable de excepción y reversión; pruebas posteriores. Si un lote trimestral o socio quedó fuera, la respuesta es «desconocido», no cero.

BTW ya analizó la migración ligada a Deprecation y Sunset. Aquí la cuestión es otra: quitar una relación del catálogo no demuestra ejecución. El servidor puede seguir después de la baja o desaparecer antes de que se quite el enlace. La discrepancia debe conservarse como evidencia.

Fuentes

Especificaciones y registros: RFC 9727, RFC Editor, IETF Datatracker, IANA well-known URI, IANA link relations, RFC 9264, RFC 8288, RFC 8615, RFC 8631, RFC 9111, RFC 9745, RFC 8594, OWASP API9:2023.

Marco analítico atribuido: Lu Heng, Nota 64, primacía del código en ejecución, por qué BTW registra la realidad.