Control de versiones

Debido a que un servicio de API puede proporcionar múltiples interfaces de API, la estrategia de control de versiones de API se aplica en el nivel de interfaz de API, en lugar de aplicarse en el nivel de servicio de API. Para mayor comodidad, el término API se refiere a las interfaces de API en las siguientes secciones.

Las API conectadas en red deben usar el Control de versiones semántico. Si el número de versión es MAJOR.MINOR.PATCH, realiza los siguientes incrementos:

  1. versión MAJOR cuando realizas cambios de API incompatibles,
  2. versión MINOR cuando agregas funcionalidad de una manera compatible con versiones anteriores,
  3. versión PATCH cuando realizas correcciones de errores compatibles con versiones anteriores.

Se aplican diferentes reglas para especificar el número de versión major según la versión de la API:

  • Para la versión 1 (v1) de una API, el número de versión major se debe codificar como el último componente del nombre del paquete de proto, por ejemplo, google.pubsub.v1. La versión major se puede omitir del nombre del paquete de proto en el caso inusual de que el paquete contenga interfaces y tipos muy estables, y que no se espere que sufran cambios rotundos, por ejemplo, google.protobuf y google.longrunning.
  • Para todas las versiones de la API que no sean la v1, el número de versión major se debe codificar como el último componente del nombre del paquete de proto. Por ejemplo, google.pubsub.v2.

Para las versiones anteriores a Google Analytics, como Alfa y Beta, se recomienda agregar un sufijo al número de versión. El sufijo debe consistir en el nombre de versión previo al lanzamiento (p. ej., Alfa o Beta) y un número de versión opcional previo al lanzamiento.

Ejemplos de progresión de versiones:

Versión Paquete de Proto Descripción
v1alpha v1alpha1 La versión Alfa v1.
v1beta1 v1beta1 La primera versión Beta v1.
v1beta2 v1beta2 La segunda versión Beta v1.
v1test v1test Una versión de prueba interna con datos ficticios.
v1 v1 La versión major v1 con disponibilidad general.
v1.1beta1 v1p1beta1 La primera versión Beta con cambios menores a v1.
v1.1 v1 La actualización menor que la versión v1.1.
v2beta1 v2beta1 La primera versión Beta v2.
v2 v2 La versión major v2 con disponibilidad general.

Los números minor y patch se deben ver reflejados en la configuración y documentación de la API. No deben estar codificados en el nombre del paquete de proto.

NOTA: La plataforma de la API de Google no admite de forma nativa las versiones minor y patch en este momento. Por cada versión major de API, hay un solo conjunto de documentación y bibliotecas cliente. Los propietarios de API deben documentarlos de forma manual a través de la documentación de la API y las notas de la versión.

Una nueva versión major de una API no debe depender de una versión major anterior de la misma API. Una API puede depender de otras API con conocimiento sobre los riesgos de dependencia y estabilidad asociados con esas API. Una versión estable de una API solo debe depender de la última versión estable de otras API.

Durante un período, las versiones diferentes de la misma API deben poder funcionar al mismo tiempo dentro de una única aplicación cliente. El objetivo es ayudar al cliente a pasar sin problemas de la versión anterior a la versión más nueva de la API.

Una versión más antigua de la API solo se debe quitar después de que finaliza el período de baja.

Los tipos de datos comunes y estables que comparten muchas API, como la fecha y la hora, se deben definir en un paquete de proto diferente. Si alguna vez se necesita un cambio rotundo, se debe ingresar un nuevo nombre de tipo o un nombre de paquete con una nueva versión major.

Compatibilidad con versiones anteriores

Puede ser difícil determinar qué es lo se considera un cambio compatible con versiones anteriores.

Las listas que aparecen a continuación son un punto de partida de referencia rápida. Si tienes alguna duda, consulta la página de compatibilidad de diseño para obtener más detalles.

Cambios compatibles con versiones anteriores (no rotundos)

  • Agregar una interfaz de API a un servicio de API
  • Agregar un método a una interfaz de API
  • Agregar una vinculación HTTP a un método
  • Agregar un campo a un mensaje de solicitud
  • Agregar un campo a un mensaje de respuesta
  • Agregar un valor a una enumeración
  • Agregar un campo de recursos de solo resultados

Cambios no compatibles con versiones anteriores (rotundos)

  • Quitar o volver a nombrar un servicio, interfaz, campo, método o valor de enum
  • Cambiar una vinculación HTTP
  • Cambiar el tipo de un campo
  • Cambiar el número de un campo de proto
  • Cambiar un formato de nombre de recurso
  • Cambiar el comportamiento visible de las solicitudes existentes
  • Cambiar el formato de URL en la definición HTTP
  • Agregar un campo de lectura o escritura a un mensaje de recurso
¿Te ha resultado útil esta página? Enviar comentarios:

Enviar comentarios sobre...