La mayoría de las aplicaciones se escriben usando alguna forma de SDK de cliente o, posiblemente, una URL de API. Las URLs de la API y del SDK de cliente están vinculadas a una versión específica de la API de Looker. Tu aplicación seguirá funcionando aunque Looker haga 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 de cliente (o modificar la URL de la API) para usar la nueva versión de la API Looker.
Cómo hace Looker cambios en la API
La API de Looker se ha diseñado para ofrecer estabilidad a los endpoints de la API de Looker y, por lo tanto, a tus aplicaciones.
A medida que añadimos más funciones y capacidades a Looker, también actualizamos la API REST de Looker para acceder a esas nuevas funciones o gestionarlas. En cada lanzamiento de Looker, añadimos 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 incompatibles, por lo que podemos mantener la versión actual de la API sin que afecte al código de ninguna aplicación creada con la API. Es posible que el código de tu aplicación no tenga en cuenta 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 romperían el código de las aplicaciones, agrupamos esos cambios en una nueva versión de la API. Esto significa que la versión antigua de la API seguirá funcionando igual que antes, mientras que una nueva versión de la API se ejecutará junto a ella con los cambios y las actualizaciones. Pueden coexistir varias versiones de la API en una sola instancia de Looker para que puedas elegir cuándo actualizar a la nueva versión de la API. El código que hayas creado para llamar al endpoint antiguo seguirá llamando al endpoint antiguo. El código nuevo debe llamar a la nueva versión del endpoint en el nivel de versión de la 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 concreta de la API, haremos todo lo necesario para mitigar ese problema de seguridad lo antes posible, lo que puede incluir inhabilitar la función vulnerable hasta que haya una solución adecuada.
Si tenemos que retirar una función o una propiedad para dar paso a una mejor implementación o solución, normalmente dejamos la API actual tal cual, pero marcamos los endpoints de la API asociados como "obsoletos" para indicar que debes dejar de usar el endpoint en el código de tu aplicación.
Cambios incompatibles y aditivos en la API
Un cambio importante es aquel que elimina o cambia el nombre de un artefacto de un endpoint de API. Puede incluir lo siguiente:
- Cambiar o eliminar el nombre o el tipo de un parámetro
- Añadir un nuevo parámetro obligatorio
- Cambiar la URL base
- Cambiar o eliminar una propiedad de una respuesta
Por otro lado, los cambios aditivos se pueden realizar en endpoints estables. Por ejemplo:
- Nuevos parámetros opcionales
- Nuevas propiedades en las respuestas (no consideramos que esto suponga un cambio radical porque damos por hecho que tu código ignorará las propiedades desconocidas en las respuestas, lo que es una práctica habitual en la comunidad de APIs REST)
Si un endpoint de la API de Looker estable necesita un cambio significativo para avanzar con una nueva arquitectura o funcionalidad, el cambio se suele añadir a un nuevo endpoint y se incluye en una nueva versión de la API para que el endpoint de la API actual no cambie.
Marcas de los endpoints de API
La mayoría de los endpoints de la API se consideran estables, lo que significa que no se espera que cambien. Looker no publicará cambios incompatibles en endpoints estables, salvo en casos extremos, como para solucionar un problema de seguridad.
Otros puntos de conexión de la API pueden estar marcados como beta o obsoletos:
- Los endpoints beta están en fase de desarrollo activo y pueden cambiar en el futuro. No están protegidas frente a cambios incompatibles. Cuando uses endpoints beta, ten en cuenta si un cambio en la API de Looker podría afectar de forma significativa a tu aplicación o ciclo de desarrollo. Lee las notas de la versión de Looker si tienes previsto usar un endpoint beta para estar al tanto de los cambios.
- Los endpoints obsoletos son endpoints que siguen admitiéndose y pueden usarse en este momento, pero se eliminarán en una versión futura. El código antiguo que usa un endpoint obsoleto debe actualizarse para dejar de usarlo. Cuando se lance una versión futura de Looker que deje de admitir ese endpoint, el código que siga usándolo dejará de funcionar. En la mayoría de los casos, un endpoint obsoleto se sustituirá por una función mejorada. Si detecta que su aplicación usa una función o una propiedad obsoletas, le recomendamos que refactorice su código para sustituir el elemento obsoleto lo antes posible.
Los endpoints beta y obsoletos se marcan como tales en el explorador de APIs y en la referencia de la API 4.0. Los endpoints que no están marcados se consideran estables.
Migrar a una nueva versión de la API
Cuando decidas actualizar la URL de la API o el SDK de cliente a una nueva versión de la API, tendrás que revisar el código de tu aplicación para comprobar si utilizas algún elemento que haya cambiado en 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 los cambios en los tipos (por ejemplo, de entero a cadena).
- Audita tu código (consulta la sección Auditar tu código).
Auditar el código
En algunos idiomas, los cambios incompatibles de la API se pueden detectar en tiempo de compilación como errores de compilación:
- Si tu aplicación está escrita en un lenguaje compilado y con tipado fuerte, los cambios estructurales en los tipos de parámetros o de respuestas de una nueva versión de la API que no coincidan con tu código deberían ser evidentes gracias a la comprobación de tipos de compilación y a los mensajes de error del compilador.
- Si tu aplicación está escrita en un lenguaje dinámico con tipado flexible (como JavaScript, Ruby y Python), puede que te resulte más difícil localizar las partes de la aplicación que se verán afectadas por los cambios incompatibles de una nueva versión de la API. Estos tipos de lenguajes pueden requerir pruebas unitarias en tiempo de ejecución para detectar cualquier problema relacionado con los cambios en los tipos.
En todos los casos, la práctica recomendada es tener pruebas unitarias que ejecuten el código de la aplicación, incluidas las llamadas a la API de Looker (no las llamadas simuladas).