La plupart des applications sont écrites à l'aide d'un SDK client ou 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 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 apporte des modifications à l'API
L'architecture de 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 de nouvelles 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 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. Votre code d'application existant peut tout simplement ignorer les nouveaux paramètres, fonctions ou fonctionnalités qui apparaîtront 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. 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. 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 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ée 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 destructive 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 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 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, 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 encore pris en charge et peuvent encore être utilisés à l'heure actuelle, 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 utiliser le point de terminaison obsolète. Lorsqu'une prochaine version de Looker ne prendra plus en charge 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 marqués comme tels dans API Explorer 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 mettre à niveau votre SDK client ou l'URL de votre API vers une nouvelle version de l'API, vous devez examiner le code de votre application pour déterminer si vous vous appuyez sur un élément qui a changé avec la nouvelle version de l'API. 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 les modifications de types (de type entier à chaîne, par exemple).
- 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 tout problème lié à des 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).