Definición
¿Alguna vez has notado cómo los periódicos y revistas se identifican por su fecha de publicación? La edición del 15 de marzo de 2024 del New York Times es una instantánea específica e identificable de las noticias de ese día. Si alguien pregunta “¿qué periódico tienes?”, la fecha les dice exactamente qué versión de información están viendo. El versionado basado en fechas aplica este mismo concepto intuitivo a las APIs: en lugar de usar números de versión abstractos como “v2.3.1”, la versión de tu API es simplemente la fecha en que fue publicada.
El versionado basado en fechas (también llamado CalVer o versionado por calendario) usa las fechas de lanzamiento como identificadores de versión. Cuando llamas a una API con la versión “2024-04-15”, sabes exactamente cuándo se publicó esa versión de la API. Este enfoque ha ganado popularidad significativa porque proporciona contexto inmediato: un número de versión como “v4” no te dice nada sobre su antigüedad o qué era del producto representa, pero “2023-01-15” te dice instantáneamente que esta versión es de enero de 2023. Stripe, una de las APIs de pagos más respetadas del mundo, fue pionera en este enfoque y ahora lo usan plataformas importantes como Twilio, GitHub y Google Cloud.
La belleza del versionado basado en fechas es que crea una línea temporal natural de la evolución de tu API. Cuando fijas tu aplicación a la versión “2022-08-01”, básicamente estás diciendo “quiero la API exactamente como existía el 1 de agosto de 2022”. Esto hace que la planificación de migraciones sea mucho más fácil: puedes ver claramente cuántas versiones atrasado estás, y los proveedores de APIs típicamente comunican cosas como “todas las versiones anteriores a 2023-01-01 serán deprecadas”. También facilita la depuración: si tu código funcionaba ayer pero se rompió hoy, puedes ver exactamente qué cambio de versión de la API pudo haberlo causado basándote en la línea temporal.
Ejemplo
Escenario Real 1: Procesamiento de Pagos con Stripe Stripe es el ejemplo emblemático del versionado basado en fechas. Cuando integras Stripe, cada cuenta está fijada a una versión específica de la API como “2023-10-16” o “2024-04-10”. Si creaste tu cuenta de Stripe en 2022, tu versión por defecto podría ser “2022-11-15”. Cuando Stripe agrega nuevas funcionalidades o cambia comportamientos, lanzan una nueva versión fechada. Puedes quedarte en tu versión actual indefinidamente, actualizar a la última, o probar contra cualquier versión intermedia. La fecha te dice exactamente cuán atrasado (o actualizado) estás.
Escenario Real 2: API de Comunicaciones de Twilio Al construir una app de mensajería con Twilio, especificas una fecha de versión como “2010-04-01” (el lanzamiento original de Twilio) o “2020-05-01” (con funcionalidades modernas). Si mantienes una app antigua que funciona perfectamente en la versión “2015-01-01”, no necesitas tocarla: esa versión sigue funcionando exactamente como está documentada. Las apps nuevas pueden usar la última versión con todas las capacidades actuales. Las fechas dejan muy claro qué documentación consultar.
Escenario Real 3: API REST de GitHub
GitHub usa versionado por fechas basado en headers: X-GitHub-Api-Version: 2022-11-28. Si estás construyendo una herramienta de CI/CD que se integra con GitHub, te fijas a una versión de fecha específica. Cuando GitHub introduce cambios incompatibles (como modificar cómo funcionan los comentarios en pull requests), lanzan una nueva versión fechada. Tu herramienta sigue funcionando en la versión antigua mientras planificas tu actualización a tu propio ritmo.
Escenario Real 4: APIs de Google Cloud Las APIs de Google Cloud usan fechas como “2023-05-01” para sus versiones de servicio. Cuando despliegas una función en la nube que llama a la Vision API de Google, especificas qué versión quieres. Si Google mejora sus algoritmos de reconocimiento de imágenes y cambia el formato de respuesta, eso va en una nueva versión fechada. Tu código existente sigue obteniendo exactamente el comportamiento para el que fue construido.
Analogía
La Analogía de las Ediciones de Periódico: Los periódicos han usado “versionado” basado en fechas por más de un siglo. La edición del 15 de marzo de 2024 es diferente de la del 16 de marzo de 2024. Si estás investigando qué sucedió en un día específico, sabes exactamente qué edición encontrar. La fecha ES la versión. Las APIs funcionan de la misma manera: la fecha te dice exactamente qué “edición” de la API estás usando.
La Analogía de la Instantánea de Software: Piensa en las versiones basadas en fechas como instantáneas en una película de viajes en el tiempo. La versión “2023-06-01” es la API congelada en el tiempo tal como existía el 1 de junio de 2023. Llamar a esa versión es como visitar ese momento exacto en la historia: todo se comporta exactamente como lo hacía entonces, sin importar qué cambios hayan ocurrido desde entonces.
La Analogía de la Cosecha de Vino: El vino se identifica por su año de cosecha: un Burdeos 2019 es distintamente diferente de un Burdeos 2020. El año te dice sobre las condiciones climáticas, la calidad de la uva y las características que puedes esperar. De manera similar, una versión de API “2024-01-01” te dice sobre las capacidades, comportamientos y funcionalidades de ese período de la evolución de la API.
La Analogía del Formulario de Impuestos Anual: Cuando presentas impuestos, usas formularios específicos para el año fiscal: el formulario de 2023 tiene reglas diferentes al formulario de 2022. Nunca usarías accidentalmente el formulario del año equivocado porque el año es prominente. Las versiones de API basadas en fechas funcionan igual: siempre sabes exactamente con qué “reglas” estás trabajando porque la fecha está ahí mismo.
Ejemplo de Código
// [Versionado](https://reference.apios.info/es/terms/versioning/) basado en fechas (estilo Stripe)
GET https://api.company.com/payments
Stripe-Version: 2024-04-10
// O en la ruta de URL
GET https://api.company.com/2024-04-10/payments
// Negociación de versión con fechas
GET https://api.company.com/payments
X-API-Version: 2024-04-10
Accept: application/json
// Respuesta con información de versión
[HTTP/1.1](https://reference.apios.info/es/terms/http-1-1/) 200 OK
X-API-Version: 2024-04-10
X-API-Version-Previous: 2023-10-16
X-API-Version-Latest: 2024-11-01
// Endpoint de changelog de versiones
GET https://api.company.com/versions
{
"versions": [
{
"date": "2024-04-10",
"changes": ["Added 3DS2 authentication", "Deprecated card tokens"],
"breaking": true
},
{
"date": "2023-10-16",
"changes": ["Added Apple Pay support", "Enhanced fraud detection"],
"breaking": false
}
],
"currentVersion": "2024-04-10",
"minimumSupported": "2023-01-01"
}