Control de versiones

En este tema, se describen las estrategias de control de versiones que usan las API de Google. En general, estas estrategias se aplican a todos los servicios administrados por Google.

A veces, es necesario realizar cambios no compatibles con las versiones anteriores (o "rotundos") en una API. Estos tipos de cambios pueden causar problemas o fallas en un código que dependa de la funcionalidad original.

Las API de Google usan un esquema de control de versiones para evitar cambios rotundos. Además, las API de Google hacen que algunas funciones solo estén disponibles en ciertos niveles de estabilidad, como los componentes Alfa y Beta.

Orientación

Todas las interfaces de la API de Google deben proporcionar un número de versión mayor, que se codifica al final del paquete protobuf y se incluye como la primera parte del Ruta de URI para las API de REST. Si una API presenta un cambio rotundo, como quitar o cambiar el nombre de un campo, debe aumentar su número de versión de API para garantizar que el código de usuario existente no se interrumpa.

Una versión principal nueva de una API no debe depender de una versión principal anterior de la misma API. Una API puede depender de otras API, con la expectativa de que el emisor comprenda el riesgo de dependencia y estabilidad asociado a esas API. En esta situación, una versión de API estable solo depende de versiones estables de otras API.

Las diferentes versiones de la misma API deben funcionar al mismo tiempo dentro de una sola aplicación cliente durante un período de transición razonable. Este período permite que el cliente realice la transición sin problemas a la versión más nueva. Una versión anterior debe pasar por un período de baja razonable y bien comunicado antes de cerrarse.

Para las versiones con estabilidad Alfa o Beta, las API deben agregar el nivel de estabilidad después del número de versión principal en el paquete protobuf y la ruta URI mediante una de las siguientes estrategias:

  • Control de versiones basado en canales (recomendado)
  • Control de versiones basado en versiones

Control de versiones basado en canales

Un canal de estabilidad es una versión de larga duración en un nivel de estabilidad determinado que recibe actualizaciones locales. No hay más de un canal por nivel de estabilidad en una versión principal. En esta estrategia, hay hasta tres canales disponibles: Alfa, Beta y estable.

Los canales Alfa y Beta deben tener el nivel de estabilidad agregado a la versión, pero el canal estable no debe tener el nivel de estabilidad agregado. Por ejemplo, v1 es una versión aceptable para el canal estable, pero v1beta o v1alpha no lo son. De manera similar, v1beta o v1alpha son versiones aceptables para los canales Alfa y Beta respectivos, pero v1 no lo es. Cada uno de estos canales recibe nuevas funciones y actualizaciones "in situ".

La funcionalidad del canal Beta debe ser un superconjunto de la funcionalidad del canal estable y la funcionalidad del canal Alfa debe ser un superconjunto de la funcionalidad del canal Beta.

Dar de baja una funcionalidad de API

Los elementos de la API (campos, mensajes, RPC) pueden marcarse como obsoletos en cualquier canal para indicar que ya no deben usarse:

// A representation of a scroll.
// Books are now preferred over scrolls.
message Scroll {
  option deprecated = true;

  // ...
}

La funcionalidad obsoleta de la API no debe pasar de Alfa a Beta ni de Beta a estable. En otras palabras, la funcionalidad no debe llegar a “obsoleto” en ningún canal.

La funcionalidad del canal Beta puede quitarse después de que se dio de baja durante un período suficiente; recomendamos 180 días. Para la funcionalidad que existe solo en el canal alfa, la baja es opcional y la funcionalidad puede quitarse sin previo aviso. Si la funcionalidad es obsoleta en el canal alfa de una API antes de la eliminación, la API debe aplicar la misma anotación y puede usar el período que desee.

Control de versiones basado en versiones

Una actualización individual es una versión Alfa o Beta que se espera que esté disponible durante un período limitado antes de que su funcionalidad se incorpore al canal estable; después de eso, la versión individual se apagará. Cuando se usa una estrategia de control de versiones basada en versiones, una API puede tener cualquier cantidad de versiones individuales en cada nivel de estabilidad.

Las versiones Alfa y Beta deben tener el nivel de estabilidad agregado a la versión, seguido de un número de versión de aumento. Por ejemplo, v1beta1 o v1alpha5. Las API deben documentar el orden cronológico de estas versiones en su documentación (como los comentarios).

Cada actualización Alfa o Beta puede actualizarse con cambios compatibles con versiones anteriores. Para las versiones Beta, las actualizaciones incompatibles con versiones anteriores deben aumentar el número de versión y publicar una nueva versión con el cambio. Por ejemplo, si la versión actual es v1beta1, entonces se libera v1beta2.

Las versiones Alfa y Beta deben cerrarse después de que su funcionalidad llegue al canal estable. Una versión Alfa puede cerrarse en cualquier momento, mientras que una versión Beta debe permitir a los usuarios un período de transición razonable; recomendamos 180 días.