RFC 9745 y su impacto en la gobernanza de API

Michel Fortes

10/06/2025 12/06/2025 Minutos 5

A Grupo de Trabajo de Ingeniería de Internet (IETF) – una organización internacional abierta que desarrolla y promueve estándares técnicos para Internet, como protocolos TCP / IP, HTTP e DNS – acaba de lanzar el RFC 9745, que define una forma estandarizada de informar la depreciación de los recursos en el contexto de HTTP, lo cual es especialmente relevante para API basado en este protocolo.

En resumen, a partir de ahora, los servidores pueden informar a sus clientes sobre el estado de desuso de ciertas funciones mediante el encabezado de respuesta. Deprecación, cuyo valor es una fecha, pasada o futura, que indica que el recurso ya se ha depreciado o se depreciará. Además, es posible usar el encabezado. enlace Para señalar la documentación y también la puesta del sol, mostrando la fecha en la que el recurso dejará de estar disponible.

En este artículo evaluaremos la viabilidad de aplicar este patrón en el mundo real. Utilizando las mejores prácticas en el desarrollo de... APIComenzaremos con los archivos de definición que siguen a la Especificación OpenAPI y terminaremos en API Puerta de enlace de KrakenD.

impactos

Como se ha dicho, esta nueva norma es especialmente importante para API web, es decir, para el API que se adhieren al protocolo HTTP, como los famosos RESTEn este contexto, la RFC proporciona un medio para llevar a cabo políticas de depreciación, anteriormente restringidas a la documentación o tiempo de diseño — en el momento de la ejecución.

Por lo tanto, esta nueva función tiene el potencial de mitigar significativamente los fallos de integración, permitiendo a los desarrolladores realizar las adaptaciones necesarias con suficiente antelación. De hecho, cabe recordar que estamos entrando en la era de la IA (con sus agentes, servidores MCP, etc.), lo que no hace más que aumentar el impacto de este nuevo estándar, ya que pueden aprender y adaptarse por sí solos ante señales de obsolescencia.

En el contexto de la gobernanza, la RFC También permite a los proveedores gateways de API (como Kong, Tyk, KrakenD, Traefik, APISix y etc.) consideran el nuevo estándar durante los procesos automatizados. desplegar de API, especialmente cuando pensamos en Operaciones API basado en OpenAPI especificación. Vamos a ver.

La especificación OpenAPI Prevé la indicación de la depreciación de las operaciones a través del campo Con esta nueva RFCEs simplemente natural para nosotros pensar en enlazar cosas, es decir, hacer que la indicación de depreciación presente en los archivos de definición coincida con la configuración de la gateways , que, una vez en ejecución, inyecta el nuevo encabezado de respuesta en las operaciones correspondientes. ¡Esta mejora elevaría la gobernanza a un nuevo nivel de calidad!

Probando el concepto

Utilizaremos el archivo de definición siguiendo Especificación OpenAPI (OEA) para describir nuestro APIVamos a construir un analizador em Go utilizando el libopenapiContaremos con el KrakenD como Puerta de enlace API y un HttpBin como backend.

Los detalles completos del proyecto se pueden encontrar en este repositorioAsí que, simplemente destacaré los puntos principales:

El archivo de definición (openapi.yaml)

rutas: (...) /usuarios/{userId}: (...) eliminar: (...) obsoleto: verdadero

Tenga en cuenta que la operación de eliminación del usuario se basa en el campo predeterminado de OEA con el valor su verdaderoBueno, es fácil ver que nos enfrentamos a un desajuste de impedancia Cuando intentamos hacer esto booleano Interactuar con los nuevos encabezados proporcionados en RFC 9745, ya que estos son mucho más ricos en información que aquel.

Por razones como ésta, la OEA tiene extensiones, que, en nuestro caso, se utilizará para describir las propiedades esperadas por el RFC de la siguiente manera:

rutas: (...) /usuarios/{userId}: (...) eliminar: (...) obsoleto: verdadero x-deprecated-at: “2025-06-30T23:59:59Z” x-deprecated-sunset: “2026-01-01T00:00:00Z” https://api.example.com/deprecation-policy

O Analizador

El papel del analizador es leer e interpretar el archivo de definición openapi.yaml, extraer la información relevante para el puerta, y crea el archivo operaciones.json, que se incrustará en la imagen de la KrakenD y se consume durante su inicialización, en un enfoque llamado configuración flexible.

Este es el resultado de operaciones.json:

{ "lista": [ { "ruta": "/usuarios", "método": "obtener", "backend": { "ruta": "/usuarios", "host": "http://backend:8888" } }, { "ruta": "/usuarios", "método": "publicar", "backend": { "ruta": "/usuarios", "host": "http://backend:8888" } }, { "ruta": "/usuarios/{IDusuario}", "método": "obtener", "backend": { "ruta": "/usuarios/{IDusuario}", "host": "http://backend:8888" } }, { "ruta": "/usuarios/{IDusuario}", "método": "eliminar", "obsoleto": { "en": "@1751327999", "enlace": "https://api.example.com/deprecation-policy", "atardecer": "Jueves, 01 de enero 2026 00:00:00 UTC" }, "backend": { "path": "/users/{userId}", "host": "http://backend:8888" } } ] }

Tenga en cuenta que el analizador diseñó los elementos extendidos del OEA en el archivo de configuración KrakenD, incluyendo la realización de las conversiones de valores correspondientes, de la siguiente manera:

OAS KrakenD x-deprecated-at: deprecated.at: x-deprecated-link: deprecated.link: x-deprecated-sunset: deprecated.sunset:

O plugin

Ahora que la configuración de la puerta se generó correctamente a partir del archivo de definición, nuestro plugin personalizado entra en juego. Su función es identificar las operaciones de API depreciado e insertar los encabezados de la RFC 9745 con los valores apropiados.

Se pueden encontrar más detalles en repositorio de artículos.Pero desde el plugin se embarcó en KrakenD, tenemos los siguientes resultados:

OBTENER /usuarios/1

ELIMINAR /usuarios/1

Téngase en cuenta que solo se depreció la segunda operación (ver operaciones.json) Y puerta Se agregaron correctamente los encabezados en la respuesta.

Conclusiones

El experimento demostró la viabilidad del concepto; es decir, que es posible llevar las políticas de depreciación más allá de la definición y la documentación, comunicándolas fácilmente en tiempo de ejecución. De esta forma, los sistemas pueden adoptar acciones automatizadas para comunicar la obsolescencia a las partes interesadas y reducir significativamente la probabilidad de fallos de integración.

Aunque las extensiones de la Especificación OpenAPI lo han hecho posible en vista de la insuficiencia de la booleano obsoletoMe imagino que el Iniciativa OpenAPI Debería incluir una mejora en las próximas versiones. Sobre todo cuando pienso que Eric Wilde, coautor de este... RFC, es muy activo en el mundo de las API.

A los lectores que han llegado hasta aquí, mi más sincero agradecimiento. Espero que estas breves palabras les hayan aportado algo y que hayan aprovechado su tiempo.