La plupart des applications sont écrites à l'aide d'une forme de SDK client ou, éventuellement, d'une URL d'API. Le SDK client et les URL d'API sont liés à une version spécifique de l'API Looker. Votre application continuera de fonctionner même si Looker apporte des modifications aux nouvelles versions de l'API. Votre application ne sera pas affectée par les modifications apportées à d'autres versions de l'API tant que vous n'aurez pas choisi de mettre à niveau votre SDK client (ou de modifier l'URL de l'API) pour utiliser la nouvelle version de l'API Looker.
Comment Looker modifie l'API
L'API Looker est conçue pour assurer la stabilité des points de terminaison de l'API Looker et, par conséquent, la stabilité de vos applications.
Lorsque nous ajoutons des fonctionnalités à Looker, nous mettons également à jour l'API REST Looker pour accéder à ces nouvelles fonctionnalités ou les gérer. Pour chaque version de Looker, nous ajoutons de nouvelles fonctions, de nouveaux paramètres et de nouvelles propriétés de type de réponse à la version actuelle de l'API Looker. Dans la plupart des cas, les ajouts à l'API ne sont pas des modifications destructives. Nous pouvons donc conserver la version existante de l'API sans affecter le code d'application existant basé sur l'API. Il est possible que votre code d'application existant ne soit pas au courant des nouvelles fonctions, des nouveaux paramètres ou des nouvelles fonctionnalités qui apparaissent dans les versions ultérieures de Looker.
Pour les modifications apportées à l'API qui interrompraient le code d'application existant, nous regroupons ces modifications destructives dans une nouvelle version de l'API. Cela signifie que l'ancienne version de l'API continuera de fonctionner comme avant, tandis qu'une nouvelle version de l'API s'exécutera en parallèle avec les modifications et les mises à jour. Plusieurs versions de l'API peuvent coexister dans une seule instance Looker. Vous pouvez ainsi choisir quand passer à la nouvelle version de l'API. Votre code existant conçu pour appeler l'ancien point de terminaison continuera de l'appeler. Le nouveau code doit appeler la nouvelle version du point de terminaison dans le niveau de version d'API le plus récent.
Une exception à cette règle concerne les problèmes de sécurité critiques. Si nous découvrons un problème de sécurité critique lié à une partie spécifique de l'API, nous ferons tout notre possible pour atténuer ce problème de sécurité dès que possible, ce qui peut inclure la désactivation de la fonctionnalité vulnérable jusqu'à ce qu'une solution appropriée soit disponible.
Si nous devons retirer une fonctionnalité, une fonction ou une propriété pour laisser place à une meilleure implémentation ou solution, nous laissons normalement l'API actuelle telle quelle, mais nous marquons les points de terminaison d'API associés comme "obsolètes" pour indiquer que vous devez les supprimer de votre code d'application.
Modifications destructives et additives apportées à l'API
Une modification destructive est une modification qui supprime ou renomme un artefact existant d'un point de terminaison d'API. Elle peut inclure les éléments suivants :
- Modification ou suppression d'un nom ou d'un type de paramètre
- Ajout d'un nouveau paramètre obligatoire
- Modification de l'URL de base
- Modification ou suppression d'une propriété existante dans une réponse
En revanche, une modification additive peut être apportée à des points de terminaison stables. Elle peut inclure les éléments suivants :
- Nouveaux paramètres facultatifs
- Nouvelles propriétés dans les réponses (nous ne considérons pas cela comme une modification destructive, car nous supposons que votre code ignorera les propriétés inconnues dans les réponses, ce qui est une pratique courante dans la communauté de l'API REST)
Si un point de terminaison d'API Looker stable nécessite une modification importante pour passer à une nouvelle architecture ou fonctionnalité, la modification est généralement ajoutée à un nouveau point de terminaison et regroupée dans une nouvelle version de l'API afin que le point de terminaison d'API existant reste inchangé.
Indicateurs pour les points de terminaison d'API
La plupart des points de terminaison d'API sont considérés comme stables, ce qui signifie qu'ils ne devraient pas changer. Looker n'apportera pas de modifications destructives aux points de terminaison stables, sauf dans des cas extrêmes, par exemple pour résoudre un problème de sécurité.
D'autres points de terminaison d'API peuvent être marqués comme bêta ou obsolètes :
- Les points de terminaison bêta sont en développement actif et peuvent être modifiés à l'avenir. Ils ne sont pas protégés contre les modifications destructives. Lorsque vous utilisez des points de terminaison bêta, déterminez si une modification apportée à l'API Looker serait particulièrement perturbatrice pour votre application ou votre cycle de développement. Veuillez lire les notes de version de Looker si vous prévoyez d'utiliser un point de terminaison bêta afin d'être informé de toute modification.
- Les points de terminaison obsolètes sont des points de terminaison qui sont toujours compatibles et peuvent encore être utilisés pour le moment, mais qui seront supprimés dans une prochaine version. L'ancien code qui utilise un point de terminaison obsolète doit être mis à jour pour cesser de l'utiliser. Lorsqu'une future version de Looker supprimera la compatibilité avec ce point de terminaison, tout code qui l'utilise encore sera interrompu. Dans la plupart des cas, un point de terminaison obsolète sera remplacé par une fonctionnalité améliorée. Si vous constatez que votre application utilise une fonction ou une propriété obsolète, il est conseillé de refactoriser votre code pour remplacer l'élément obsolète dès que possible.
Les points de terminaison bêta et obsolètes sont marqués comme tels dans l'API Explorer et dans la documentation de référence de l'API 4.0. Les points de terminaison qui ne sont pas marqués sont considérés comme stables.
Types d'appels d'API
Les types d'appels d'API définis comme appels d'API de requête sont les suivants :
- Appels requis pour les pipelines de requêtes automatisés
- Appels qui récupèrent des données à partir de la base de données client
- Appels qui exécutent des requêtes SQL ou récupèrent des résultats pour le contenu
Voici quelques exemples :
Les types d'appels d'API définis comme appels d'API d'administration sont les suivants :
- Appels requis pour créer des applications, contrôler le contenu entre les instances et effectuer des tâches administratives
- Appels qui contrôlent l'instance Looker (Google Cloud Core)
- Appels qui effectuent la gestion du contenu, la gestion des autorisations et des utilisateurs, l'administration des instances ou l'extraction de contenu entre les dossiers
Voici quelques exemples :
Migrer vers une nouvelle version de l'API
Lorsque vous choisissez de mettre à niveau votre SDK client ou votre URL d'API vers une nouvelle version de l'API, vous devez examiner le code de votre application pour voir si vous utilisez un élément qui a changé avec la nouvelle version de l'API. Veillez à procéder comme suit :
- Recherchez les noms de fonctions, de valeurs et de propriétés mis à jour dans le code de votre application.
- Vérifiez que le code de votre application est compatible avec les modifications de types (par exemple, passage d'un entier à une chaîne).
- Effectuez un audit de votre code (consultez la section Effectuer un audit de votre code).
Effectuer un audit de votre code
Pour certains langages, les modifications destructives apportées à l'API peuvent être détectées au moment de la compilation sous forme d'erreurs de compilation :
- Si votre application est écrite dans un langage compilé et fortement typé, les modifications structurelles apportées aux types de paramètres ou de réponses dans une nouvelle version de l'API qui sont en conflit avec votre code existant devraient être facilement visibles grâce à la vérification du type de compilation et aux messages d'erreur du compilateur.
- Si votre application est écrite dans un langage dynamique faiblement typé (tel que JavaScript, Ruby et Python), il peut être plus difficile de localiser les parties de votre application qui seront affectées par les modifications destructives apportées à une nouvelle version de l'API. Ces types de langages peuvent nécessiter des tests unitaires d'exécution pour détecter les problèmes liés aux modifications de types.
Dans tous les cas, la bonne pratique consiste à effectuer des tests unitaires qui exercent le code de votre application, y compris les appels à l'API Looker (et non les appels simulés).