La plupart des applications sont écrites à l'aide d'un SDK client ou 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 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 de nouvelles fonctions, paramètres et 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, 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 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 d'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 dans le niveau de version de l'API le plus récent.
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 abandonner une fonctionnalité, une fonction ou une propriété pour laisser la place à une meilleure implémentation ou solution, nous laissons généralement l'API actuelle telle quelle, mais nous marquons les points de terminaison de l'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 cela comme une erreur, car nous supposons que votre code ignore 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 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 empaqueté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 d'API sont considérés comme stables, ce qui signifie qu'ils ne devraient pas changer. Looker ne publiera pas de modifications incompatibles 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 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, réfléchissez à l'impact d'une modification de l'API Looker sur 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 est 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 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 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 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. Assurez-vous de procéder comme suit:
- Recherchez les noms de fonction, de valeur et de propriété mis à jour dans le code de votre application.
- 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 certaines langues, les modifications non compatibles 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é à 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 faible (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 exercent le code de votre application, y compris les appels à l'API Looker (et non les appels simulés).