Deprecación de API: definición, buenas prácticas y ejemplos

¿Qué es la deprecación de una API?

La deprecación de una API es el proceso formal de retirar un endpoint, una versión, un parámetro o un campo de respuesta. Lo obsoleto sigue funcionando durante un periodo anunciado mientras se informa a los consumidores de qué usar en su lugar. Al final de ese periodo se elimina, lo que se llama sunset, y quien siga llamándolo recibe errores.

Es el contrato entre quien ofrece la API y quienes la consumen: esto cambia, esta es la fecha, este es el reemplazo.

El ciclo de vida de la deprecación

Cómo señalarlo en HTTP

Dos cabeceras de respuesta estándar hacen que la deprecación sea legible por máquinas. Deprecation (RFC 9745, marzo de 2025) indica que el recurso está o estará obsoleto, con una fecha escrita como @ seguida de segundos Unix. Sunset (RFC 8594) indica cuándo se espera que deje de responder, con una fecha HTTP que no debería ser anterior a la de deprecación. Una cabecera Link con rel="deprecation" puede apuntar a la documentación.

HTTP/1.1 200 OK
Deprecation: @1780272000
Sunset: Tue, 01 Dec 2026 00:00:00 GMT
Link: <https://api.example.com/docs/v1-sunset>; rel="deprecation"; type="text/html"
Content-Type: application/json

Ambas cabeceras son avisos orientativos. No cambian el comportamiento del endpoint y los clientes solo se benefician si algo las lee, así que anuncia también por correo y en la documentación.

Qué se puede deprecar

• Una versión completa de la API, como v1 a favor de v2.
• Un único endpoint, por ejemplo uno sustituido por una nueva ruta.
• Un parámetro de petición o un campo de respuesta, por ejemplo created sustituido por created_at.
• Un método de autenticación, como las claves de API a favor de OAuth 2.0.
• Un tipo de evento de webhook o un método de SDK.

Buenas prácticas

• Anuncia con antelación. Da a los consumidores tiempo suficiente para planificar el trabajo. No hay una cifra universal: GitHub, por ejemplo, mantiene una versión anterior de su API REST al menos 24 meses después de publicar una nueva.
• Documenta la ruta de migración. Muestra la correspondencia entre lo antiguo y lo nuevo con ejemplos de código, no solo "usa la nueva API".
• Usa las cabeceras y un changelog. Haz que el cambio sea fácil de encontrar para máquinas y personas.
• Contacta directamente con los consumidores. Escribe a los titulares de cuenta y muestra un aviso dentro del producto. Pocos leen un blog.
• Controla quién sigue llamando a la versión antigua. Registra el uso por endpoint y por consumidor (clave de API, cliente OAuth) para llegar a las personas adecuadas.
• Publica primero el reemplazo. Ejecuta lo antiguo y lo nuevo en paralelo y mantén los SDK al día.
• Ensaya la retirada. Una caída breve y anunciada (brownout) de la versión antigua saca a la luz clientes olvidados antes del corte real.
• Devuelve 410 Gone tras el sunset. MDN lo describe como que el recurso ya no está disponible y probablemente de forma permanente. Usa 404 si no sabes si es permanente.

Errores habituales

• Retirada silenciosa. Sin aviso, clientes enfadados.
• Sin guía de migración. Los consumidores tienen que deducir la diferencia por su cuenta.
• Una ventana más corta que el ciclo de versiones de tus clientes. Los equipos que publican cada trimestre no pueden moverse en unas semanas.
• Eliminar un campo que aún se usa. Comprueba antes el uso.
• Olvidar SDK y documentación. Siguen enviando a la gente a la versión antigua.
• Deprecar sin reemplazo. Los consumidores no tienen adónde ir.
• Anunciar solo en un blog. Añade cabeceras, correo y avisos dentro del producto.

Ejemplos de APIs reales

API REST de GitHub. Las versiones se nombran por fecha y se eligen con la cabecera X-GitHub-Api-Version. Las peticiones sin ella usan 2022-11-28 y, al publicarse una versión nueva, la anterior sigue soportada al menos 24 meses (documentación de GitHub).

API GraphQL de GitHub. GitHub anuncia los cambios incompatibles del esquema con al menos tres meses de antelación y los aplica el primer día de un trimestre. Las próximas eliminaciones se listan en su página de cambios incompatibles (documentación de GitHub).

Stripe. Las peticiones usan la versión de API predeterminada de la cuenta salvo que la sustituyas con la cabecera Stripe-Version, de modo que actualizas cuando estés listo. Desde la versión 2024-09-30, Stripe publica versiones mensuales sin cambios incompatibles y, dos veces al año, una versión mayor con cambios incompatibles (documentación de Stripe).

Pruebas y monitorización durante la ventana de deprecación

Mientras conviven dos versiones, comprueba las dos. Las pruebas de API que comparan respuestas antiguas y nuevas detectan desviaciones de comportamiento antes que tus consumidores, y la guía para importar cURL, HAR, Postman y OpenAPI muestra cómo convertir peticiones existentes en pruebas de carga. La monitorización de API de LoadFocus puede ejecutar un check por endpoint y versión, validar código de estado, cabeceras y cuerpo, y avisarte si el reemplazo empieza a fallar o a ir lento. Los checks gratuitos se ejecutan cada 5 minutos.

Haz también una prueba de carga de la versión nueva con el tráfico combinado de ambas, porque es lo que soportará tras el sunset. Las pruebas de carga de LoadFocus ejecutan scripts de JMeter y k6 para ello.

Preguntas frecuentes: deprecación de API

¿Cuánto debe durar la ventana de sunset?

Depende de quiénes sean tus consumidores. Una API pública usada por muchos equipos necesita más tiempo que una interna con pocos clientes conocidos. GitHub, por ejemplo, mantiene una versión anterior de su API REST al menos 24 meses. Mide cuánto necesitan tus consumidores más lentos y añade margen.

¿Qué diferencia hay entre deprecación y sunset?

La deprecación es el anuncio: aún funciona, pero no construyas sobre ello. El sunset es la fecha en que deja de funcionar.

¿Debo versionar mi API?

Sí, si alguien ajeno a tu equipo depende de ella. Las versiones en la URL, como /v1/, son las más fáciles de ver y probar. Las versiones por cabecera o por fecha, como las de GitHub y Stripe, mantienen estables las URL pero son más fáciles de usar mal.

¿Qué estado HTTP debe devolver un endpoint retirado?

410 Gone es el más claro. MDN señala que los clientes no deben repetir peticiones a un 410 y que 404 es la opción cuando no sabes si la retirada es permanente.

¿Cómo sé quién sigue llamando a un endpoint obsoleto?

Registra cada petición con un identificador de consumidor, como la clave de API o el ID de cliente OAuth, y cuenta las llamadas por consumidor y día. Contacta primero con los que más lo usan.

¿Añadir un campo es un cambio incompatible?

Normalmente no, por eso los cambios aditivos rara vez requieren deprecación. Eliminar un campo, renombrarlo o cambiar su significado sí.