Google, Azure y Stripe versionan sus API de tres formas y coinciden en una regla
Las tres compañías aplican estrategias distintas de versionado, pero solo tocan la versión cuando el cambio no se puede hacer compatible hacia atrás.
Google, Microsoft y Stripe versionan sus API de tres maneras distintas y ninguna se parece a la de los otros. Google mete la versión en la ruta y se queda en v1: no existe v1.1 ni v1.4.2. Azure exige un parámetro de consulta ?api-version= con fecha y no pone nada en la ruta. Stripe usa versiones rodantes con nombre de fecha y ancla cada cuenta a la versión con la que llamó por primera vez. Las tres son defendibles.
En qué coinciden
El criterio común es más interesante que las diferencias: solo se versiona cuando el cambio no puede hacerse compatible hacia atrás. Todo lo demás se despliega sin tocar el número.
Los ejemplos de cambio seguro son añadir un campo opcional, publicar un endpoint nuevo o incorporar un parámetro opcional. Los que rompen son quitar un campo, renombrarlo, cambiarle el tipo o convertir un parámetro opcional en obligatorio. Es la lista de siempre, pero aplicada con disciplina.
Jubilar una versión tiene cabeceras estándar
Para retirar versiones antiguas hay dos cabeceras que conviene conocer. La cabecera Deprecation, definida en el RFC 9745, arranca el reloj: en el ejemplo del texto viaja como marca de tiempo Unix (@1688169599). La cabecera Sunset, del RFC 8594, marca cuándo se acaba el plazo con una fecha HTTP completa. El texto usa Sat, 31 Dec 2026 23:59:59 GMT como muestra.
La fecha de sunset nunca puede ser anterior a la de deprecation, y el texto es explícito en que el cliente debe tratarla como una pista, no como una garantía: nada obliga al proveedor a mantener el servicio hasta ese día.
Lo que falta
El autor anuncia una comparación de las cuatro estrategias en una tabla, un proceso de versionado en seis pasos y el procedimiento para retirar una versión de verdad. Nada de eso está desarrollado en el texto: queda como resumen y remite a material aparte.
Para quien diseña o mantiene una API pública, el valor está en el criterio, no en el formato. Elegir entre ruta, query param o versión por fecha es una decisión de arquitectura que arrastras años, y las tres compañías demuestran que no hay una respuesta única. Lo que sí se puede copiar es la regla de no versionar por costumbre y la de publicar deprecation y sunset con antelación suficiente para que un cliente planifique una migración.
