Introduction
La console de gestion de Talend Cloud, que nous vous présentions dans un précédent article est entièrement « APIfiée ». Cela veut dire que tout ce que nous voyons et pouvons faire dessus peut se déclencher et se récupérer grâce à des appels API Rest. Cela permet par exemple d’automatiser des tâches (création d’utilisateur(s) et affectation des droits), de déléguer les actions, et de stocker dans des services externes les informations (par exemple pour faire du monitoring custom).
La documentation de ces API, que l’on appel plus communément le swagger, nous informe que cette version des API est dépréciée depuis la Release R2024-03 et qu’elle sera supprimée lors de la Release R2025-09.
Si vous utilisez cette version d’API, vous avez donc un an pour la mettre à jour.
Quels sont les changements et impacts ? Comment ça fonctionne ? Que devez-vous faire ? Nous allons répondre à ces questions dans cet article.
Migration vers la nouvelle API
Changements d’URL des ressources
La procédure de migration de l’API v2.6 vers les nouveaux domaines et présentée dans le Guide Utilisateur des API Talend Cloud. Cette dernière fait la correspondance, par ressource entre les anciens chemins des URI et les nouveaux chemins.
Sur ce mapping, nous pouvons voir qu’il n’y a pas de grosse différence. Le changement entre l’ancienne et la nouvelle API est l’ajout d’un premier niveau dans l’URI, afin de catégoriser les routes : Security, Orchesration, Processing…
Changement de l’URL de base
L’URL de base diffère entre les deux API. :
- Ancienne URL : https://api.eu.cloud.talend.com/tmc/v2.6
- Nouvelle URL : https://api.eu.cloud.talend.com/
Là ou dans l’ancienne URL était spécifiée la version de l’API, la nouvelle ne contient que la base de l’URL. Maintenant, La version de l’api est spécifiée dans l’entête de la requête.
Version de l’API
La politique de gestion des versions de l’API est décrite dans https://api.talend.com/api-versioning-policy/
La version se spécifie dans l’en tête avec la clé talend-version, avec comme pattern YYYY-MM, sachant que la version actuelle est la 2021-03
Si la version spécifiée n’existe pas, ou s’il n’y a pas de version précisée dans l’entête de la requête, alors c’est la version la plus ancienne qui est utilisée.
Inscrivez-vous à la newsletter DeciVision !
Soyez notifiés de nos derniers articles de blog, de nos prochains webinars et nos actualités !
Contenu des réponses d’appels des API
Quand est-il des données renvoyées par ces API ? Le format de la réponse a-t-il changé ?
Pour rappel, lorsque l’on appelle une API, celle-ci nous renvoi le résultat sous un format compréhensible et exploitable, principalement au format JSON, ou XML. Pour savoir si le format de la réponse de ces API a changé, nous avons développé un job Talend qui, par route, appelle l’ancienne et la nouvelle URI, et compare le résultat. Nous nous sommes basés sur une liste d’API que nous utilisons sur un projet interne à DeciVision.
Pour donner plus de précision sur le fonctionnement du job Talend utilisé, celui :
- Lit un fichier CSV dans lequel sont stockés les anciennes et nouvelles URI dont le format est :
Pour chaque ligne nous :
- Exécutons ces API et stockons les résultats dans 2 fichiers différents
- Comparons le contenu des 2 fichiers
- Ecrivons le résultat de la comparaison dans un dernier fichier de comparaison.
Après exécution du job, nous avons le résultat suivant :
Nous constatons que la réponse de ces appels API est différente pour 3 d’entre elles.
Nous analysons la différence manuellement afin d’évaluer les changements à apporter. Nous utilisons Notepad ++ avec les plugins JsonTools (Formater le json en triant les objets par ordre croissant) et Compare (comparaison des 2 fichiers).
Analyse des différences
Plans
L’analyse manuelle des résultats de /orchestration/executables/plans nous montre que
- L’objet items.chart.stepdId est renommé en items.chart.id
- L’objet items.chart.stepName est renommé en items.chart.name
- L’objet items.chart.flow.stepdId est renommé en items.chart.flow.id
- L’objet items.chart.flow.stepName est renommé en items.chart.flox.name
- Un tableau est ajouté : chart.nextSteps.taskIds[]
- L’objet items.chart.nextStep.flows.plan n’existe plus
Plan Exécution
Les objets de la réponse de l’API /processing/executables/plans/executions sont dans un ordre différent, mais ces objets et leur contenu est identique.
Task Execution
Pour /processing/executables/tasks/exécutions Tout comme la réponse d’API sur l’exécution des plans, le résultat KO de comparaison est un faux positif, car seul l’ordre des objets de la réponse diffère. Les objets sont identiques.
En effet, dans la documentation de la nouvelle version, il est indiqué que la réponse JSON est une collection non ordonnée de champs, et que cet ordre peut changer. Il est donc fortement déconseillé de se fier à l’ordre de ces éléments.
CONCLUSION DE L’EXPERT
Si vous utilisez les API Public de la TMC Talend, vous allez devoir modifier l’URL de base, ainsi que les URI d’appels des ressources pour continuer à les utiliser. Les modifications ne sont pas importantes, mais il est nécessaire de les faire car la version 2.6 sera décommissionnée lors de la Release R2025-09, et de ne pas attendre son décommissionnement, afin d’évaluer les différences, comme nous vous avons présenté dans cet article de blog.
Il existe un nombre important d’API que nous ne les avons pas toutes analysées. Il se peut qu’il y ait des changements dans les appels de type GET, qui renvoient une réponse, comme pour l’API /orchestration/executables/plans
N’hésitez pas à solliciter DeciVision si vous avez des questions, vous souhaitez que l’on vous assiste sur ces migrations ou sur tout autre sujet autour de Talend ou de nos domaines d’expertise.
