La mayoría de las aplicaciones se escriben con alguna forma de SDK del cliente o, posiblemente, una URL de API. Las URLs de la API y el SDK del cliente están vinculadas a una versión específica de la API de Looker. Tu aplicación seguirá funcionando incluso cuando Looker realice cambios en las nuevas versiones de la API. Tu aplicación no se verá afectada por los cambios en otras versiones de la API hasta que decidas actualizar tu SDK del cliente (o modificar la URL de la API) para usar la nueva versión de la API de Looker.
Cómo Looker realiza cambios en la API
La API de Looker está diseñada para proporcionar estabilidad a los extremos de la API de Looker y, por lo tanto, estabilidad a tus aplicaciones.
A medida que agregamos más funciones y capacidades a Looker, también actualizamos la API de REST de Looker para acceder a esas funciones nuevas o administrarlas. En cada versión de Looker, agregamos nuevas funciones, parámetros y propiedades de tipo de respuesta de la API a la versión actual de la API de Looker. En la mayoría de los casos, las adiciones a la API no son cambios rotundos, por lo que podemos mantener la versión existente de la API sin afectar el código de la aplicación existente que se basa en la API. Es posible que tu código de la aplicación existente simplemente no conozca las nuevas funciones, los parámetros o las características que aparecen en las versiones posteriores de Looker.
En el caso de los cambios en la API que interrumpirían el código de la aplicación existente, los agrupamos en una nueva versión de la API. Esto significa que la versión anterior de la API seguirá funcionando igual que antes, mientras que una nueva versión de la API se ejecutará junto con ella con los cambios y las actualizaciones. Pueden existir varias versiones de la API en paralelo en una sola instancia de Looker, de modo que puedas elegir cuándo actualizar a la nueva versión de la API. Tu código existente, que se compiló para llamar al extremo anterior, seguirá llamando al extremo anterior. El código nuevo debe llamar a la versión nueva del extremo en el nivel de versión de API más reciente.
Una excepción a esta regla son los problemas de seguridad críticos. Si descubrimos un problema de seguridad crítico relacionado con una parte específica de la API, haremos todo lo necesario para mitigar ese problema de seguridad lo antes posible, lo que puede incluir inhabilitar la funcionalidad vulnerable hasta que haya una solución adecuada.
Si necesitamos retirar una función o propiedad para dar paso a una mejor implementación o solución, normalmente dejamos la API actual tal como está, pero marcamos los extremos de API asociados como "obsoletos" para indicar que debes dejar de usar el extremo en el código de tu aplicación.
Cambios rotundos y aditivos en la API
Un cambio rotundo es aquel que borra o cambia el nombre de un artefacto existente de un extremo de API. Puede incluir lo siguiente:
- Cambiar o borrar el nombre o el tipo de un parámetro
- Agregar un nuevo parámetro obligatorio
- Cómo cambiar la URL base
- Cómo cambiar o borrar una propiedad existente en una respuesta
Por otro lado, se puede realizar un cambio aditivo en los extremos estables. Pueden incluir lo siguiente:
- Parámetros nuevos y opcionales
- Nuevas propiedades en las respuestas (no consideramos que esto sea un cambio que genere errores porque suponemos que tu código ignorará las propiedades desconocidas en las respuestas, lo que es una práctica común en la comunidad de la API de REST)
Si un extremo estable de la API de Looker necesita un cambio significativo para avanzar con una nueva arquitectura o funcionalidad, el cambio suele agregarse a un extremo nuevo y se incluye en una nueva versión de la API para que el extremo de API existente permanezca sin cambios.
Marcas para extremos de API
La mayoría de los extremos de API se consideran estables, lo que significa que no se espera que cambien. Looker no lanzará cambios que interrumpan la compatibilidad en los endpoints estables, excepto en casos extremos, como para corregir un problema de seguridad.
Otros extremos de API pueden marcarse como beta o obsoletos:
- Los endpoints beta están en desarrollo activo y pueden cambiar en el futuro. No están protegidas contra cambios rotundos. Cuando uses extremos beta, considera si un cambio en la API de Looker sería particularmente perjudicial para tu app o ciclo de desarrollo. Si planeas usar un extremo beta, lee las notas de la versión de Looker para conocer los cambios.
- Los extremos obsoletos son extremos que aún se admiten y se pueden usar en este momento, pero se borrarán en una versión futura. El código anterior que usa un extremo obsoleto debe actualizarse para dejar de usarlo. Cuando una versión futura de Looker deje de admitir ese extremo, se interrumpirá cualquier código que aún lo use. En la mayoría de los casos, un extremo en desuso se reemplazará por una funcionalidad mejorada. Si descubres que tu aplicación usa una función o propiedad obsoleta, es una buena idea reestructurar el código para reemplazar el elemento obsoleto lo antes posible.
Los endpoints en versión beta y los obsoletos se marcan como tales en el Explorador de API y en la Referencia de la API 4.0. Los extremos que no están marcados se consideran estables.
Tipos de llamadas a la API
Los tipos de llamadas a la API que se definen como llamadas a la API de consulta son los siguientes:
- Llamadas necesarias para las canalizaciones de consultas automatizadas
- Llamadas que obtienen datos de la base de datos del cliente
- Llamadas que ejecutan consultas en SQL o recuperan resultados para el contenido
Algunos ejemplos son los siguientes:
Los tipos de llamadas a la API que se definen como llamadas a la API de administrador son los siguientes:
- Llamadas necesarias para compilar aplicaciones, controlar el contenido en las instancias y realizar tareas administrativas
- Llamadas que controlan la instancia de Looker (Google Cloud Core)
- Llamadas que realizan la administración de contenido, la administración de permisos y usuarios, la administración de instancias o la extracción de contenido de carpetas
Los ejemplos incluyen:
Cómo migrar a una nueva versión de la API
Cuando elijas actualizar la URL de la API o el SDK del cliente a una nueva versión de la API, deberás revisar el código de tu aplicación para ver si dependes de algo que haya cambiado con la nueva versión de la API. Asegúrate de hacer lo siguiente:
- Busca en el código de tu aplicación los nombres actualizados de las funciones, los valores y las propiedades.
- Verifica que el código de tu aplicación admita cualquier cambio en los tipos (como de número entero a cadena).
- Audita tu código (consulta la sección sobre cómo auditar tu código).
Audita tu código
En algunos lenguajes, los cambios breaking en la API se pueden descubrir en el momento de la compilación como errores de compilación:
- Si tu aplicación está escrita en un lenguaje compilado y con escritura sólida, los cambios estructurales en los tipos de parámetros o respuestas en una nueva versión de la API que no coincidan con tu código existente deberían ser evidentes gracias a la verificación de tipos de compilación y los mensajes de error del compilador.
- Si tu aplicación está escrita en un lenguaje dinámico con escritura flexible (como JavaScript, Ruby y Python), puede ser más difícil ubicar las partes de la aplicación que se verán afectadas por los cambios que generen interrupciones en una nueva versión de la API. Estos tipos de lenguajes pueden requerir pruebas de unidades en tiempo de ejecución para encontrar cualquier problema relacionado con los cambios en los tipos.
En todos los casos, la práctica recomendada es tener pruebas de unidades que ejerciten el código de tu aplicación, incluidas las llamadas a la API de Looker (no las llamadas simuladas).