La mayoría de las aplicaciones se escriben con algún tipo de SDK cliente o, posiblemente, una URL de API. El SDK cliente y las URLs de la API están vinculados a una versión específica de la API de Looker. Tu aplicación seguirá funcionando incluso mientras Looker realice cambios en las nuevas versiones de la API. Tu aplicación no se verá afectada por los cambios realizados en otras versiones de la API hasta que elijas actualizar el SDK 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 arquitectura de 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. Para 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 incorporaciones a la API no son cambios rotundos, por lo que podemos conservar la versión existente de la API sin afectar ningún código de aplicación existente compilado en la API. Es posible que el código de la aplicación existente simplemente no esté al tanto de las funciones, los parámetros o las características nuevos que aparecerán en las versiones posteriores de Looker.
Para los cambios en la API que rompen el código de la aplicación existente, agrupamos esos cambios rotundos en una nueva versión de API. Esto significa que la versión antigua de la API seguirá funcionando como antes, mientras que una nueva versión de la API se ejecutará junto con los cambios y actualizaciones. Pueden existir varias versiones de la API una al lado de la otra en una sola instancia de Looker para que puedas elegir cuándo actualizar a la nueva versión de la API. El código existente que se compiló para llamar al extremo anterior seguirá llamando al extremo anterior. El código nuevo debe llamar a la nueva versión del extremo en el nivel de versión de API más reciente.
La única excepción 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 lo antes posible, lo que puede incluir inhabilitar la funcionalidad vulnerable hasta que se disponga de una solución adecuada.
Si necesitamos retirar una función, una función o una propiedad para implementar una mejor implementación o solución, por lo general, dejamos la API actual como está, pero marcamos los extremos de la API asociados como “obsoletos” para indicar que debes alejarte del extremo en el código de la aplicación.
Cambios rotundos y aditivos en la API
Un cambio rotundo es algo que borra un artefacto existente de un extremo de API o le cambia el nombre. Puede incluir lo siguiente:
- Cambia o borra el nombre o el tipo de parámetro
- Cómo 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
- Propiedades nuevas en las respuestas (no consideramos que esto falle porque suponemos que tu código ignorará las propiedades desconocidas en las respuestas, lo cual 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 arquitectura o funcionalidad nuevas, por lo general, el cambio se agrega a un extremo nuevo y se agrupa en una nueva versión de la API para que el extremo de la API existente permanezca sin cambios.
Marcas para los extremos de la API
La mayoría de los extremos de la API se consideran estables, lo que significa que no se espera que cambien. Looker no lanzará cambios rotundos en extremos estables, excepto en casos extremos, como para solucionar problemas de seguridad.
Otros extremos de la API pueden marcarse como obsoletos o beta:
- Los extremos beta están en desarrollo activo y pueden cambiar en el futuro. No están protegidas de cambios rotundos. Cuando uses extremos beta, considera si un cambio en la API de Looker sería particularmente disruptivo para tu app o ciclo de desarrollo. Consulta las notas de la versión de Looker si planeas usar un extremo beta para estar al tanto de los cambios.
- Los extremos obsoletos son extremos que todavía son compatibles y que se pueden usar en este momento, pero se borrarán en una versión futura. El código antiguo que usa un extremo obsoleto se debe actualizar para dejar de usar el extremo obsoleto. Cuando una versión futura de Looker quite la compatibilidad con ese extremo, cualquier código que aún lo use fallará. En la mayoría de los casos, un extremo obsoleto se reemplazará por una funcionalidad mejorada. Si descubres que tu aplicación está usando una función o propiedad obsoleta, te recomendamos refactorizar tu código para reemplazar el elemento obsoleto lo antes posible.
Los extremos beta y obsoletos se marcan como tales en el Explorador de APIs y en la Referencia de la API 4.0. Los extremos que no están marcados se consideran estables.
Migra a una versión nueva de la API
Cuando elijas actualizar el SDK cliente o la URL de tu API 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 cambió 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 la función, el valor y las propiedades.
- Verifica que el código de la aplicación admita cualquier cambio en los tipos (como de número entero a string).
- Audita tu código (consulta la sección Auditoría de tu código).
Auditoría de tu código
Para algunos lenguajes, se pueden descubrir cambios rotundos en la API durante el tiempo de compilación como errores de compilación:
- Si tu aplicación está escrita en un lenguaje compilado con tipado fuerte, los cambios estructurales en los tipos de respuesta o parámetros en una nueva versión de API que están en desacuerdo con tu código existente deberían ser evidentes gracias a la comprobación del tipo de compilación y los mensajes de error del compilador.
- Si tu aplicación está escrita en un lenguaje dinámico con tipos poco definidos (como JavaScript, Ruby y Python), puede ser más difícil localizar las partes de tu aplicación que se verán afectadas por los cambios rotundos en una nueva versión de la API. Estos tipos de lenguajes pueden requerir pruebas de unidades de tiempo de ejecución para encontrar problemas relacionados con los cambios en los tipos.
En todos los casos, la práctica recomendada es realizar pruebas de unidades que ejerzan el código de la aplicación, incluidas las llamadas a la API de Looker (no las llamadas simuladas).