Control de versiones

Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

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 en los componentes alfa y beta.

Orientación

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

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 llamador comprenda la dependencia y el riesgo de estabilidad asociados con esas API. En este caso, una versión estable de la API debe depender solo de versiones estables de otras API.

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

En el caso de las versiones que tienen estabilidad Alfa o Beta, las API deben agregar el nivel de estabilidad después del número de versión principal del paquete protobuf y la ruta del URI mediante una de las siguientes opciones: estas estrategias:

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

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 in situ. No hay más de un canal por nivel de estabilidad para una versión principal. En esta estrategia, hay hasta tres canales disponibles: Alfa, Beta y estable.

El canal alfa y el canal beta deben tener adjunto su nivel de estabilidad, pero el canal estable no debe tener agregado el nivel de estabilidad. 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 es aceptable para ninguna de las dos. Cada uno de estos canales recibe nuevas funciones y actualizaciones “en el lugar”.

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.

Baja de la funcionalidad de la API

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

// Represents a scroll. Books are preferred over scrolls.
message Scroll {
  option deprecated = true;

  // ...
}

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

La funcionalidad del canal Beta puede quitarse después de que se considere obsoleta durante un período suficiente. Recomendamos 180 días. Para las funciones que existen solo en el canal alfa, la baja es opcional y las funcionalidades podrían quitarse sin previo aviso. Si la funcionalidad está obsoleta en el canal alfa de una API antes de su eliminación, la API debe aplicar la misma anotación y podría usar cualquier 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 en el canal estable, después de lo cual se podrá lanzar la versión individual. apagar. Cuando se utiliza una estrategia de control de versiones basada en versiones, una API puede tener cualquier cantidad de versiones individuales en cada nivel de estabilidad.

En las versiones Alfa y Beta, se debe agregar el nivel de estabilidad a la versión, seguido de un número de versión incremental. Por ejemplo, v1beta1 o v1alpha5. Las API deben documentar el orden cronológico de estas versiones en la documentación (como los comentarios).

Cada versión Alfa o Beta puede actualizarse en su lugar con cambios compatibles con versiones anteriores. En el caso de las versiones beta, las actualizaciones incompatibles con las versiones anteriores deben realizarse mediante el aumento del número de versión y la publicación de una versión nueva con el cambio. Por ejemplo, si la versión actual es v1beta1, se lanzará v1beta2 a continuación.

Las versiones alfa y beta deben cerrarse después de que su funcionalidad alcance el 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.

Control de versiones basado en la visibilidad

La visibilidad de la API es una función avanzada que proporciona la infraestructura de la API de Google. Permite que los productores de API expongan varias vistas externas de la API desde una superficie de API interna, y cada vista se asocia con una etiqueta de visibilidad de la API, como la siguiente:

import "google/api/visibility.proto";

message Resource {
  string name = 1;

  // Preview. Do not use this feature for production.
  string display_name = 2
    [(google.api.field_visibility).restriction = "PREVIEW"];
}

Una etiqueta de visibilidad es una string que distingue entre mayúsculas y minúsculas y se puede usar para etiquetar cualquier elemento de la API. Por convención, las etiquetas de visibilidad siempre deben usar mayúsculas. Se aplica una etiqueta PUBLIC implícita a todos los elementos de la API, a menos que se aplique una etiqueta de visibilidad explícita, como en el ejemplo anterior.

Cada etiqueta de visibilidad es una lista de elementos permitidos. Los productores de API deben otorgar etiquetas de visibilidad a los consumidores de la API para que puedan usar las funciones de la API asociadas con las etiquetas. En otras palabras, una etiqueta de visibilidad de API es como una versión de API con LCA.

Se pueden aplicar varias etiquetas de visibilidad a un elemento con una string separada por comas (p. ej., "PREVIEW,TRUSTED_TESTER"). Cuando se usan varias etiquetas de visibilidad, el cliente solo necesita una de las etiquetas de visibilidad (OR lógica).

Una misma solicitud a la API solo puede usar una etiqueta de visibilidad. De forma predeterminada, se usa la etiqueta de visibilidad otorgada al consumidor de la API. Un cliente puede enviar solicitudes con una etiqueta de visibilidad explícita de la siguiente manera:

GET /v1/projects/my-project/topics HTTP/1.1
Host: pubsub.googleapis.com
Authorization: Bearer y29....
X-Goog-Visibilities: PREVIEW

Los productores de API pueden usar la visibilidad de la API para el control de versiones de la API, como INTERNAL y PREVIEW. Una nueva función de la API comienza con la etiqueta INTERNAL y, luego, se mueve a la etiqueta PREVIEW. Cuando la función es estable y está disponible para el público general, todas las etiquetas de visibilidad de la API se quitan de la definición de la API.

En general, la visibilidad de la API es más fácil de implementar que el control de versiones de la API para cambios incrementales, pero depende de la compatibilidad sofisticada con la infraestructura de API. Las API de Google Cloud a menudo usan la visibilidad de la API para las funciones de vista previa.