Definición
Imagina que eres un propietario que necesita demoler un edificio antiguo para construir uno nuevo. No aparecerías una mañana con una bola de demolición: les darías a los inquilinos meses (o años) de aviso, les ayudarías a encontrar nuevos apartamentos, proporcionarías asistencia para la mudanza, y solo procederías con la demolición después de que todos se hubieran reubicado de forma segura. Una política de deprecación es exactamente este tipo de plan de transición considerado, pero para APIs. Es el acuerdo formal entre un proveedor de API y sus usuarios sobre cómo se eliminarán gradualmente las funcionalidades antiguas, cuánto aviso se dará y qué soporte se proporcionará durante la transición.
Sin una política de deprecación clara, los consumidores de APIs viven en constante temor. ¿Desaparecerá de repente el endpoint del que dependen? ¿Se romperá su aplicación sin aviso? Una buena política de deprecación elimina esta ansiedad al establecer reglas predecibles. Típicamente incluye: cuánto aviso previo se dará (a menudo de 6 a 24 meses), cómo se comunicará la deprecación (email, headers de respuesta de la API, anuncios en el portal de desarrolladores), qué ruta de migración o alternativa se proporcionará, y la fecha exacta en que la API antigua dejará de funcionar (llamada la “fecha de sunset”). Los principales proveedores de APIs como Google, Microsoft y AWS publican sus políticas de deprecación de forma prominente, tratándolas como compromisos vinculantes con sus comunidades de desarrolladores.
Una política de deprecación se trata fundamentalmente de respeto por el tiempo e inversión de tus usuarios. Cuando los desarrolladores construyen aplicaciones sobre tu API, están haciendo una apuesta de que su código seguirá funcionando. La política de deprecación es tu promesa sobre las reglas de esa apuesta: no que las cosas nunca cambiarán, sino que los cambios se comunicarán de forma justa y las transiciones se gestionarán de manera responsable. Las mejores políticas dan a los desarrolladores la confianza de que no se despertarán con aplicaciones rotas, y que cuando lleguen los cambios, tendrán tiempo y recursos adecuados para adaptarse.
Ejemplo
Escenario Real 1: Política de 12 Meses de Google Cloud Las APIs de Google Cloud siguen una política de deprecación estricta: al menos 12 meses de aviso antes de cualquier cambio incompatible, con documentación de migración clara proporcionada en el momento del anuncio. Cuando Google deprecó su Cloud ML Engine a favor de Vertex AI, lo anunciaron en enero de 2023 con una fecha de sunset de enero de 2025, dando a los equipos dos años completos para migrar. Durante este período, ML Engine siguió funcionando normalmente, se publicaron guías de migración, y los equipos de soporte ayudaron con las transiciones.
Escenario Real 2: Ventana Continua de Stripe Stripe mantiene las versiones de API disponibles durante años y usa una política de deprecación que garantiza compatibilidad hacia atrás dentro de las líneas de versiones principales. Cuando deprecaron ciertas APIs de tokens de tarjeta, enviaron notificaciones por email con 18 meses de anticipación, agregaron advertencias de deprecación a las respuestas de la API, destacaron el cambio en el dashboard de desarrolladores, y proporcionaron ejemplos de código para el nuevo enfoque. El método antiguo siguió funcionando hasta la fecha de sunset, con advertencias cada vez más prominentes a medida que se acercaba la fecha.
Escenario Real 3: Versionado del Graph API de Facebook Facebook (Meta) tiene una política de deprecación de dos años para las versiones del Graph API. Cuando lanzan la versión 18.0, la versión 16.0 (lanzada dos años antes) entra en su período de sunset. Los desarrolladores reciben emails automatizados, advertencias en el dashboard, y las llamadas a la API afectadas empiezan a devolver headers de deprecación. La política es predecible: sabes que cualquier versión funcionará durante al menos dos años después del lanzamiento, dándote un horizonte de planificación claro.
Escenario Real 4: Eliminación Gradual de Twilio Cuando Twilio deprecó su API original de Programmable Voice a favor de una nueva arquitectura, implementaron una deprecación por etapas: Mes 0 - anuncio y guía de migración; Mes 6 - headers de advertencia agregados a las respuestas; Mes 12 - emails a todas las cuentas afectadas; Mes 18 - congelación de funcionalidades en la API antigua; Mes 24 - sunset con respuestas 410 Gone. Cada etapa se comunicó claramente, dando a los desarrolladores múltiples puntos de contacto para planificar su migración.
Analogía
El Anuncio de Cierre de Carretera: Cuando una ciudad necesita cerrar una autopista importante para reconstrucción, no pone barreras de la noche a la mañana. Hay señales con meses de anticipación: “Autopista 101 cerrando agosto 2025. Use ruta alternativa vía Autopista 85.” Se construyen rutas de desvío temporales. Se transmiten actualizaciones de tráfico. Se notifica a los negocios locales. Solo después de una preparación extensiva ocurre el cierre real. Las políticas de deprecación de APIs funcionan idénticamente: son el sistema de aviso anticipado que permite a todos prepararse.
El Aviso de Reubicación de Tienda: Cuando tu tienda favorita se muda a una nueva ubicación, los buenos negocios te dan suficiente aviso. Ponen letreros en la ubicación antigua, envían emails a los miembros del programa de fidelidad, actualizan su sitio web, y a menudo operan ambas ubicaciones brevemente. No simplemente cierran las puertas un día. Una política de deprecación es este aviso de mudanza para APIs: diciéndole a los usuarios dónde ir, cuándo cierra la ubicación antigua, y asegurando una transición suave.
El Cronograma de Graduación: Las escuelas no gradúan estudiantes de repente: hay un cronograma claro. En el primer año, sabes cuándo te graduarás. Las universidades publican catálogos diciendo “este plan de estudios es válido para estudiantes que entren 2024-2028”. Si los requisitos cambian, los estudiantes existentes mantienen las reglas antiguas. Las políticas de deprecación de APIs proporcionan garantías similares: una vez que estás usando la versión X, conoces las reglas que te aplican.
La Eliminación Gradual de Medicamentos con Receta: Cuando las compañías farmacéuticas discontinúan medicamentos, hay un proceso muy regulado. Los médicos son notificados con meses de anticipación. Los pacientes son transicionados a alternativas. Las farmacias almacenan suficiente suministro para el período de transición. Nadie encuentra de repente que su receta no está disponible. Este enfoque cuidadoso y regulado es exactamente lo que una buena política de deprecación de APIs proporciona al mundo del software.
Ejemplo de Código
// Headers de deprecación (RFC 8594)
GET /v1/products
[HTTP/1.1](https://reference.apios.info/es/terms/http-1-1/) 200 OK
Deprecation: true
Sunset: Sat, 31 Dec 2025 23:59:59 GMT
Link: <https://api.company.com/v2/products>; rel="successor-version"
Link: <https://docs.company.com/migration>; rel="deprecation"
Warning: 299 - "API v1 deprecated, migrate to v2 by 2025-12-31"
// Endpoint de deprecaciones
GET https://api.company.com/deprecations
{
"deprecations": [
{
"endpoint": "/v1/products",
"version": "1.0",
"announcedDate": "2024-06-01",
"sunsetDate": "2025-12-31",
"reason": "Replaced by more efficient v2 with pagination",
"migrationGuide": "https://docs.company.com/v1-to-v2",
"successorEndpoint": "/v2/products",
"breakingChanges": [
"Response now paginated",
"New authentication required"
],
"supportContact": "[email protected]"
}
]
}
// Cronograma típico de deprecación
// Mes 0: Anunciar deprecación, publicar guía de migración
// Mes 3: Agregar advertencias de deprecación a las respuestas
// Mes 6: Email a todos los consumidores de la API
// Mes 9: Empezar a devolver advertencias 299
// Mes 12: Fecha de sunset - devolver 410 Gone
GET /v1/products
HTTP/1.1 410 Gone
{
"error": "EndpointGone",
"message": "This endpoint was sunset on 2025-12-31",
"successor": "https://api.company.com/v2/products"
}