La plupart des applications sont écrites à l'aide d'un SDK client ou éventuellement d'une URL d'API. Le SDK client et les URL de l'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 dans les 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 apporte des modifications à l'API
L'architecture de l'API Looker assure la stabilité des points de terminaison de l'API Looker, et donc de la stabilité 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 des fonctions, des paramètres et des 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 constituent pas des modifications destructives. Nous pouvons donc conserver la version existante de l'API sans affecter le code d'application existant créé à partir de l'API. Il se peut que votre code d'application existant ignore simplement les nouvelles fonctions, paramètres ou fonctionnalités qui apparaissent dans les versions suivantes de Looker.
Pour les modifications de l'API qui entraîneraient le dysfonctionnement du code d'application existant, nous regrouperons ces modifications destructives dans une nouvelle version de l'API. Cela signifie que l'ancienne version de l'API continuera de fonctionner comme auparavant, tandis qu'une nouvelle version d'API s'exécutera avec les modifications et les mises à jour. Plusieurs versions de l'API peuvent être placées côte à côte dans une même instance Looker. Vous pouvez ainsi choisir quand passer à la nouvelle version de l'API. Le code existant qui a été créé pour appeler l'ancien point de terminaison continuera d'appeler l'ancien point de terminaison. Le nouveau code doit appeler la nouvelle version du point de terminaison au niveau de la version d'API le plus récent.
Les problèmes de sécurité critiques font exception à cette règle. Si nous identifions un problème de sécurité critique lié à une partie particulière de l'API, nous ferons tout ce qui est nécessaire pour le résoudre dès que possible, y compris en désactivant la fonctionnalité vulnérable jusqu'à ce qu'une solution appropriée soit disponible.
Si nous devons supprimer une fonctionnalité, une fonction ou une propriété dans le but d'améliorer une implémentation ou une solution, nous laissons normalement l'API actuelle telle quelle, mais nous indiquons que les points de terminaison de l'API associés sont "obsolètes" dans votre code d'application.
Modifications destructives et supplémentaires dans l'API
Une modification destructive permet de supprimer ou de renommer un artefact existant d'un point de terminaison d'API. Il peut s'agir des éléments suivants:
- Modifier ou supprimer un nom ou un type de paramètre
- Ajouter un paramètre obligatoire
- Modifier l'URL de base
- Modification ou suppression d'une propriété existante dans une réponse
En revanche, des modifications additives peuvent être apportées 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 cette rupture, car nous supposons que votre code ignore les propriétés inconnues dans les réponses, ce qui est courant 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 de l'API existant reste inchangé.
Indicateurs de points de terminaison de l'API
La plupart des points de terminaison de l'API sont considérés comme stables, c'est-à-dire qu'ils ne devraient pas changer. Looker ne publiera pas de modifications destructives sur des 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 de l'API peuvent être signalés comme étant en version bêta ou obsolètes:
- Les points de terminaison bêta sont en cours de développement et sont susceptibles de changer à l'avenir. Ils ne sont pas protégés contre les modifications destructives. Lorsque vous utilisez des points de terminaison bêta, demandez-vous si une modification de l'API Looker serait particulièrement gênante pour votre application ou votre cycle de développement. Veuillez consulter les notes de version de Looker si vous prévoyez d'utiliser un point de terminaison bêta pour être informé des modifications.
- Les points de terminaison obsolètes sont des points de terminaison toujours compatibles et qui peuvent être utilisés à l'heure actuelle, mais qui seront supprimés dans une prochaine version. Vous devez mettre à jour l'ancien code utilisant un point de terminaison obsolète pour qu'il cesse d'utiliser le point de terminaison obsolète. Lorsqu'une prochaine version de Looker supprimera la compatibilité avec ce point de terminaison, le code qui l'utilise encore ne fonctionnera plus. 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, nous vous recommandons de refactoriser le code 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.
Migrer vers une nouvelle version de l'API
Lorsque vous choisissez de mettre à jour le SDK client ou l'URL de l'API vers une nouvelle version de l'API, vous devez examiner le code de votre application. Assurez-vous de procéder comme suit:
- Dans le code de votre application, recherchez les noms de fonction, de valeur et de propriété mis à jour.
- Vérifiez que le code de votre application est compatible avec toute modification de type (par exemple, un entier à chaîne).
- Auditez votre code (voir la section ci-dessous).
Auditer votre code
Pour certains langages, des modifications destructives dans l'API peuvent être détectées au moment de la compilation en tant qu'erreurs de compilation:
- Si votre application est écrite dans un langage compilé et fortement typé, les modifications structurelles apportées aux paramètres ou aux types de réponse dans une nouvelle version de l'API qui contredisent votre code existant devraient être facilement identifiables 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 de type faible (tel que JavaScript, Ruby et Python), il peut être plus difficile de localiser les parties de votre application concernées par les modifications destructives dans une nouvelle version de l'API. Ces types de langages peuvent nécessiter des tests unitaires d'exécution pour identifier les problèmes liés aux modifications des types.
Dans tous les cas, la bonne pratique consiste à effectuer des tests unitaires pour exercer votre code d'application, y compris des appels à l'API Looker (et non des appels fictifs).