La plupart des applications sont écrites à l'aide d'une forme de SDK client ou éventuellement d'une URL d'API. Les URL du SDK client et de l'API sont liées à 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 aux 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, de vos applications.
À mesure que 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 qui est basé sur l'API. Il est possible que votre code d'application existant ne connaisse tout simplement pas les nouvelles fonctions, les nouveaux paramètres ou les nouvelles fonctionnalités qui apparaissent dans les versions ultérieures de Looker.
Pour les modifications apportées à l'API qui pourraient casser le code d'application existant, nous regroupons ces modifications majeures 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 d'API peuvent coexister dans une même 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.
Les problèmes de sécurité critiques font exception à cette règle. 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 l'atténuer dès que possible. Cela 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 généralement 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. Voici quelques exemples :
- Modifier ou supprimer le nom ou le type d'un paramètre
- Ajouter un paramètre obligatoire
- Modifier l'URL de base
- Modifier ou supprimer une propriété existante dans une réponse
En revanche, une modification additive peut être apportée aux points de terminaison stables. Voici quelques exemples :
- Nouveaux paramètres facultatifs
- Nouvelles propriétés dans les réponses (nous ne considérons pas cela comme une modification destructrice, 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é des API REST)
Si un point de terminaison stable de l'API Looker 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 de l'API existant reste inchangé.
Indicateurs pour les points de terminaison d'API
La plupart des points de terminaison de l'API sont considérés comme stables, ce qui signifie qu'ils ne devraient pas changer. Looker n'apporte pas de modifications incompatibles 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 signalés comme bêta ou obsolètes :
- Les points de terminaison bêta sont en cours de développement et peuvent être modifiés à l'avenir. Elles ne sont pas protégées contre les modifications importantes. Lorsque vous utilisez des points de terminaison bêta, déterminez si une modification de l'API Looker perturberait particulièrement 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 tout changement.
- 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 ne plus l'utiliser. Lorsqu'une future version de Looker ne prendra plus en charge ce point de terminaison, tout code qui l'utilisera encore cessera de fonctionner. 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 indiqué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 obtiennent des données 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 nécessaires pour créer des applications, contrôler le contenu dans 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, des autorisations et des utilisateurs, l'administration des instances ou l'extraction de contenu dans des 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 vous appuyez sur un élément qui a changé avec la nouvelle version de l'API. Veillez à effectuer les opérations suivantes :
- 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 prend en charge les modifications de types (par exemple, d'entier à chaîne).
- Auditez votre code (consultez la section Auditer votre code).
Auditer votre code
Pour certaines langues, les modifications incompatibles de 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 contradiction avec votre code existant devraient être facilement apparentes 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 à typage faible (comme JavaScript, Ruby et Python), il peut être plus difficile de localiser les parties de votre application qui seront affectées par les modifications incompatibles dans 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).