La plupart des applications sont écrites à l'aide d'un SDK client ou d'une URL d'API. Le SDK client et les URL d'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 des 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'architecture de l'API Looker est conçue pour offrir de la stabilité aux 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, paramètres et propriétés de type de réponse de l'API à 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 basé sur l'API. Il est possible que votre code d'application existant ne soit tout simplement pas au courant des nouveaux paramètres, fonctions ou fonctionnalités qui apparaîtront dans les versions suivantes de Looker.
En cas de modifications de l'API susceptibles de rompre le code d'application existant, nous regroupons ces modifications destructives dans une nouvelle version de l'API. L'ancienne version de l'API continue de fonctionner comme avant, tandis qu'une nouvelle version de l'API s'exécute en parallèle avec les modifications et les mises à jour. Plusieurs versions d'API peuvent exister côte à côte dans une même instance Looker, afin que vous puissiez choisir quand effectuer la mise à niveau vers la nouvelle version de l'API. Le code existant créé pour appeler l'ancien point de terminaison continuera d'appeler cet ancien point de terminaison. Le nouveau code doit appeler la nouvelle version du point de terminaison au niveau de version d'API le plus récent.
La seule exception concerne les problèmes de sécurité critiques. Si nous découvrons un problème de sécurité critique lié à une partie particulière de l'API, nous prendrons les mesures nécessaires pour atténuer le problème dans les meilleurs délais, en désactivant par exemple 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 améliorer l'implémentation ou la solution, nous ne changeons généralement pas l'API actuelle, mais nous marquons les points de terminaison de l'API associés comme "obsolètes" pour indiquer que vous devez vous en éloigner dans le code de votre application.
Modifications destructives et complémentaires de l'API
Une modification destructive permet de supprimer ou de renommer un artefact existant d'un point de terminaison de l'API. Cela peut inclure:
- Modifier ou supprimer un nom ou un type de paramètre
- Ajouter un paramètre obligatoire
- Modifier l'URL de base
- Modifier ou supprimer une propriété existante dans une réponse
Une modification additive, en revanche, 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 cette interruption, 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 d'API Looker stable nécessite une modification importante pour aller plus loin avec une nouvelle architecture ou fonctionnalité, la modification est généralement ajoutée à un nouveau point de terminaison et intégrée à 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 sont pas censés changer. Looker n'apportera pas de modifications destructives 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 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 destructives. Lorsque vous utilisez des points de terminaison bêta, demandez-vous si une modification de l'API Looker affecterait particulièrement 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 afin d'être au courant de toutes les modifications.
- Les points de terminaison obsolètes sont toujours compatibles et peuvent encore être utilisés pour le moment, mais ils seront supprimés dans une prochaine version. L'ancien code qui utilise un point de terminaison obsolète doit être mis à jour pour cesser d'utiliser ce point de terminaison. Lorsqu'une prochaine version de Looker supprime la prise en charge de 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 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 afin de 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.
Migrer vers une nouvelle version de l'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 afin de déterminer si vous utilisez 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 accepte les modifications de types (par exemple, de entier à chaîne).
- Auditez votre code (voir la section ci-dessous).
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é à forte typage, les modifications structurelles des paramètres ou des types de réponse dans une nouvelle version de l'API qui contredisent votre code existant devraient être facilement visibles 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 aux types peu typés (JavaScript, Ruby et Python, par exemple), il peut être plus difficile de localiser les parties de votre application qui seront affectées par des modifications destructives 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 des types.
Dans tous les cas, il est recommandé d'effectuer des tests unitaires qui exécutent le code de votre application, y compris les appels à l'API Looker (et non les appels simulés).