La plupart des applications sont écrites à l'aide d'un SDK client ou éventuellement d'une URL d'API. Les URL du SDK client et de l'API sont associé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. Les modifications apportées aux autres versions de l'API n'affecteront pas votre application tant que vous ne choisirez pas 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-t-il l'API ?
L'API Looker est conçue pour assurer la stabilité des points de terminaison de l'API Looker, et donc de vos applications.
À mesure que nous ajoutons de nouvelles fonctionnalités à Looker, nous mettons à jour l'API REST de Looker pour accéder à ces nouvelles fonctionnalités ou les gérer. Pour chaque version de Looker, nous ajoutons de nouvelles fonctions d'API, 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 constituent pas des modifications majeures. 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 tout simplement pas au courant des nouvelles fonctions, paramètres ou fonctionnalités qui apparaissent dans les versions ultérieures de Looker.
Pour les modifications de l'API qui endommageraient le code d'application existant, nous regroupons ces modifications dans une nouvelle version de l'API. Cela signifie que l'ancienne version de l'API continuera à fonctionner de la même manière qu'auparavant, tandis qu'une nouvelle version de l'API s'exécutera en même temps que les modifications et mises à jour. Plusieurs versions d'API peuvent coexister dans une même instance Looker côte à côte, ce qui vous permet de choisir quand effectuer la mise à niveau vers la nouvelle version de l'API. Votre code existant, qui a été créé pour appeler l'ancien point de terminaison, continuera de l'appeler. Le nouveau code doit appeler la nouvelle version du point de terminaison au niveau de la version d'API la plus récente.
Une exception à cette règle concerne les problèmes de sécurité critiques. Si nous détectons un problème de sécurité critique lié à une partie spécifique de l'API, nous ferons tout notre possible pour le résoudre 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 supprimer une fonctionnalité, une fonction ou une propriété pour faire place à une meilleure implémentation ou solution, nous laissons normalement l'API actuelle, mais nous marquons les points de terminaison d'API associés comme "obsolètes" pour indiquer que vous devez vous éloigner du point de terminaison dans le code de votre application.
Modifications destructives et additives apportées à l'API
Une modification destructrice consiste à supprimer ou à renommer un artefact existant d'un point de terminaison d'API. Cela peut inclure :
- 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 que cela a des conséquences, 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 stable de l'API Looker nécessite une modification importante pour adopter une nouvelle architecture ou fonctionnalité, la modification est généralement ajoutée à un nouveau point de terminaison et intégrée dans une nouvelle version de l'API afin que le point de terminaison existant de l'API reste inchangé.
Indicateurs pour les points de terminaison de l'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 ne publiera pas de modifications majeures sur les 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 bêta ou obsolètes:
- Les points de terminaison bêta sont en cours de développement et sont susceptibles de changer à l'avenir. Elles ne sont pas protégées contre les modifications importantes. Lorsque vous utilisez des points de terminaison bêta, demandez-vous si un changement de l'API Looker serait particulièrement perturbateur pour votre application ou votre cycle de développement. Si vous prévoyez d'utiliser un point de terminaison bêta, veuillez lire les notes de version de Looker pour connaître les modifications.
- Les points de terminaison obsolètes sont des points de terminaison qui sont toujours pris en charge et peuvent toujours ê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 prochaine version de Looker ne sera plus compatible avec ce point de terminaison, tout code qui l'utilise encore ne fonctionnera plus. Dans la plupart des cas, un point de terminaison obsolète sera remplacé par des fonctionnalités améliorées. Si vous constatez que votre application utilise une fonction ou une propriété obsolète, nous vous recommandons 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'explorateur d'API et dans la documentation de référence de l'API 4.0. Les points de terminaison non marqués sont considérés comme stables.
Migrer vers une nouvelle version d'API
Lorsque vous choisissez de passer à 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. Veillez à 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 accepte les modifications de types (par exemple, de l'entier à la chaîne).
- Effectuez un audit de votre code (voir la section Effectuer un audit de votre code).
Auditer votre code
Pour certains langages, les modifications destructives de l'API peuvent être découvertes au moment de la compilation en tant qu'erreurs de compilation:
- Si votre application est écrite dans un langage compilé à typage fort, les modifications structurelles apportées aux types de paramètres ou de réponses dans une nouvelle version d'API qui sont en contradiction avec votre code existant devraient être facilement visibles grâce au contrôle de type de compilation et aux messages d'erreur du compilateur.
- Si votre application est écrite dans un langage dynamique à typage dynamique (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 non compatibles d'une nouvelle version d'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, il est recommandé d'avoir des tests unitaires qui exécutent le code de votre application, y compris les appels à l'API Looker (et non les appels simulés).