La mayoría de las aplicaciones se escriben con algún formato de SDK de cliente o, posiblemente, de una URL de API. El SDK del cliente y las URL de las API están vinculadas a una versión específica de la API de Looker. Tu aplicación seguirá funcionando incluso si Looker realiza 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 cliente (o modificar la URL de la API) para usar la nueva versión.
Cómo Looker realiza cambios en la API
La API de Looker está diseñada para proporcionar estabilidad a los extremos de la API y, por lo tanto, a las 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 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 ningún código de la aplicación compilado en la API. Es posible que el código de tu aplicación existente no tenga en cuenta las funciones, los parámetros o las funciones nuevas que aparecen en las versiones posteriores de Looker.
Para los cambios en la API que dañarían el código de la aplicación existente, agrupamos esos cambios rotundos en una nueva versión de la API. Esto significa que la versión de API anterior seguirá funcionando como antes, mientras que se ejecutará una versión de API nueva junto con los cambios y las actualizaciones. Puede haber varias versiones de la API en paralelo 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 creó 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 esto es por problemas de seguridad críticos. Si descubrimos un problema crítico de seguridad 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 la inhabilitación de la funcionalidad vulnerable hasta que haya una solución adecuada disponible.
Si necesitamos retirar una función, una función o una propiedad para mejorar una implementación o solución, en general, dejamos la API actual tal como está, pero marcamos los extremos de la API asociados como "obsoleto" para indicar que debes alejarte del extremo del código de tu aplicación.
Cambios rotundos y aditivos en la API
Un cambio rotundo es un elemento que borra o renombra un artefacto existente de un extremo de API. Podría incluir lo siguiente:
- Cambiar o borrar el nombre o el tipo de un parámetro
- Cómo agregar un nuevo parámetro obligatorio
- Cómo cambiar la URL base
- Cambiar o borrar una propiedad existente en una respuesta
Por otro lado, un cambio aditivo puede realizarse en los extremos estables. Pueden incluir lo siguiente:
- Parámetros nuevos opcionales
- Nuevas propiedades en las respuestas (no consideramos esta interrupción 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 de la API de Looker estable necesita un cambio significativo para avanzar con una arquitectura o funcionalidad nuevas, el cambio se suele agregar a un extremo nuevo y se agrupa en una versión de API nueva a fin de que el extremo de API existente no se modifique.
Marcas para extremos de API
La mayoría de los extremos de API se consideran stable, lo que significa que no se espera que cambien. Looker no lanzará cambios rotundos en extremos estables, excepto en casos extremos, como para solucionar un problema de seguridad.
Otros extremos de API se pueden marcar como beta o obsoletos:
- Los extremos 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 podría ser particularmente disruptivo para tu app o tu ciclo de desarrollo. Lee las notas de la versión de Looker si planeas usar un extremo beta para estar al tanto de cualquier cambio.
- Los extremos obsoletos son extremos que aún son compatibles 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 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 notas que tu aplicación usa una función o propiedad obsoleta, te recomendamos refactorizar tu código para reemplazar el elemento obsoleto lo antes posible.
Los extremos beta o obsoletos se marcan como en el Explorador de API y en la Referencia de API 4.0. Los extremos que no están marcados se consideran estables.
Cómo migrar a una nueva versión de la API
Cuando decidas actualizar la API de SDK o la URL del cliente a una nueva versión de la API, deberás revisar el código de la aplicación para ver si necesitas algo que haya cambiado con la nueva versión de la API. Asegúrate de hacer lo siguiente:
- Busca en el código de la aplicación la función actualizada, el valor y los nombres de las propiedades.
- Verifica que el código de tu aplicación admita cualquier cambio de tipo (como de entero a string).
- Audita tu código (consulta la siguiente sección).
Audita el código
Para algunos lenguajes, los cambios rotundos de la API se pueden detectar en el tiempo de compilación como errores de compilación:
- Si tu aplicación está escrita en un lenguaje compilado de fuerte tipo, los cambios estructurales a los tipos de parámetros o respuestas en una nueva versión de la 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 de tipo general (como JavaScript, Ruby y Python), es posible que sea más difícil encontrar las partes de tu aplicación que se verán afectadas si se realizan cambios rotundos en una nueva versión de la API. Es posible que estos tipos de lenguajes requieran pruebas de unidades de tiempo de ejecución para detectar problemas relacionados con cambios en los tipos.
En todos los casos, la práctica recomendada es tener pruebas de unidades que apliquen el código de tu aplicación, incluidas las llamadas a la API de Looker (no llamadas simuladas).