Le versionnement de l’API chez Workiva
Le versionnement des interfaces de programmation d’applications (API) est une pratique essentielle qui consiste à attribuer des identifiants uniques aux différentes itérations de la conception d’une API afin de gérer et de communiquer les changements de manière efficace. Son objectif principal est de maintenir la compatibilité ascendante, en veillant à ce que les scripts et les applications reposant sur une ancienne version ne soient pas interrompus lorsqu’une nouvelle version de l’API est publiée. Cette stabilité permet aux fournisseurs d’API d’introduire des mises à jour majeures, des corrections de bogues et de nouvelles fonctionnalités sans perturber les utilisateurs existants, ce qui donne aux consommateurs le temps et le contrôle nécessaires pour migrer leurs systèmes lorsqu’ils sont prêts. En fin de compte, un versionnement approprié de l’API favorise un écosystème de développement fiable, évolutif et professionnel.
2026-01-01 Version de l’API
En janvier 2026, Workiva publiera une nouvelle version de l’API, 2026-01-01. Cette nouvelle version apporte des améliorations significatives dans de nombreux domaines, y compris une meilleure cohérence, de nouvelles fonctionnalités et l’abandon de fonctionnalités existantes. Les avantages de la mise à niveau vers la version 2026-01-01 incluent une compatibilité continue avec les dernières fonctionnalités de la plateforme Workiva, une sécurité renforcée, des performances améliorées et la possibilité d’exploiter de nouvelles fonctionnalités.
Pour plus d’informations sur la nouvelle version de l’API, consultez le Workiva API 2026-01-01 Upgrade Guide.
Déclassement de la version 2022-01-01 de l’API
Avec la publication de la version 2026-01-01, l’ancienne version 2022-01-01 entrera dans sa phase d’obsolescence. L’assistance pour cette ancienne version se poursuivra jusqu’à son expiration en janvier 2029, et l’assistance pour les terminaux du prototype 2022-01-01 se terminera en janvier 2027.
Note : La plupart des points d’extrémité du prototype de la version 2022-01-01 ont été promus à la disponibilité générale (GA) dans la version 2026-01-01.
| Version | État | Type d’extrémité | Date du coucher du soleil |
|---|---|---|---|
| 2026-01-01 | Disponibilité générale (AG) | Tout | N/A (Actuel) |
| 2022-01-01 | Déprécié | Prototype | janvier 2027 |
| 2022-01-01 | Déprécié | GA | janvier 2029 |
Comparaison des versions de l’API
Lorsqu’une nouvelle version est publiée, la documentation de l’API pour cette version sur le Workiva Developers Hub comprend une section Changelog qui inclut une documentation détaillée sur les changements de l’API dans cette version. La version 2026-01-01 comportera une section 2026-01-01 Upgrade Guide avec une description complète des modifications apportées à cette version.
En outre, il existe de nombreux outils open source permettant d’effectuer une comparaison entre deux versions différentes de l’API. Ces types d’outils permettent des comparaisons rapides et détaillées des changements de version. L’outil open source oasdiff dispose d’un calculateur de différences basé sur le web qui vous permet de télécharger deux fichiers de configuration de la version de l’API (oas.yaml) et d’effectuer une comparaison des changements de rupture, des journaux de modification ou d’une différence brute. Il peut produire des résultats en texte, yaml, json, html et markdown.
Référencez une version spécifique de l’API
Les API de Workiva s’appuient sur l’en-tête X-Version pour spécifier la version de l’API à utiliser. Si l’en-tête X-Version n’est pas transmis, la version par défaut est la version dépréciée 2022-01-01.
Note : Après janvier 2029, l’en-tête X-Version sera obligatoire et tous les appels à l’API qui en seront dépourvus échoueront.
Pour spécifier la version dans une demande d’API via Python, incluez la paire clé/valeur dans les en-têtes de chaque demande d’API. Par exemple : headers = {’X-Version’ : ’2026-01-01’}
Actuellement, vous pouvez spécifier 2026-01-01 ou 2022-01-01.
Étant donné que la version 2026-01-01 comporte de nombreux changements radicaux, il est essentiel de s’assurer que l’en-tête X-Version est défini pour la version applicable et que le chemin et les paramètres de l’URL de l’extrémité de l’API correspondent à la structure requise de cette version. En outre, il est important de comprendre le format de réponse de l’appel à l’API et toute différence potentielle de ce format entre les versions.
Exemples
Exemple de requête GET
Voici un exemple d’utilisation d’une requête GET dans le point de terminaison Retrieve a List of Spreadsheets pour les versions 2026-01-01 et 2022-01-01 (ces exemples incluent le bearer token comme variable token à des fins d’obscurcissement dans cet article).
Version 2026-01-01
# 2026-01-01 version # notez l’en-tête X-Version et l’URL de la requête headers = { ’Accept’ : ’application/json’, ’Authorization’ : token, ’X-Version’ : ’2026-01-01’, } resp = requests.get( ’https ://api.app.wdesk.com/spreadsheets’, headers = headers, )Version 2022-01-01
# version 2022-01-01 # notez l’en-tête X-Version et l’URL de la requête headers = { ’Accept’ : ’application/json’, ’Authorization’ : token, ’X-Version’ : ’2022-01-01’, } resp = requests.get( ’https ://api.app.wdesk.com/platform/v1/spreadsheets’, headers = headers, ) Exemple de demande PATCH
Vous trouverez ci-dessous un exemple d’utilisation d’une requête PATCH dans le point de terminaison « Partially Update a Single Section » pour les versions 2026-01-01 et 2022-01-01 (ces exemples incluent le bearer token comme variable token dans cet article à des fins d’obscurcissement).
2026-01-01 version
# 2026-01-01 version # notez l’en-tête X-Version et l’URL des requêtes headers = { ’Content-Type’ : ’application/json’, ’Accept’ : ’application/json’, ’Authorization’ :token, ’X-Version’ : ’2026-01-01’, } patch_op = [ { « op » : « replace », « path » : « /name », « value » : « My New Section Name » } ] resp = requêtes.patch ( https ://api.app.wdesk.com/documents/{documentId}/sections/{sectionId}’, json = patch_op, headers = headers, ) 2022-01-01 version
# 2022-01-01 version # notez l’en-tête X-Version et l’URL des requêtes headers = { ’Content-Type’ : ’application/json’, ’Accept’ : ’application/json’, ’Authorization’ : token, ’X-Version’ : ’2022-01-01’, } patch_op = [ { « op » : « replace », « path » : « /name », « value » : « My New Section Name » } ] resp = requests.patch( f’https ://api.app.wdesk.com/platform/v1/documents/{documentId}/sections/{sectionId}’, json = patch_op, headers = headers, ) Conseil : En plus de vous assurer que le chemin d’accès à l’URL et la structure des paramètres correspondent à la version de l’API applicable, veillez à consulter la documentation pour obtenir des détails sur les options de paramètres disponibles.
Par exemple, dans l’exemple de mise à jour partielle d’une section unique ci-dessus, la version 2022-01-01 propose trois options de chemin d’accès ( /name , /index , /parent ), mais la version 2026-01-01 propose plus de trente options de chemin d’accès.
Meilleures pratiques en matière de scripts et de versions d’API
Bien que la version spécifique de l’API dont vous avez besoin puisse dépendre de l’état des scripts et des applications actifs, des délais de mise à niveau vers la nouvelle version de l’API ou d’autres facteurs, vous trouverez ci-dessous quelques bonnes pratiques relatives aux scripts et au versionnement de l’API.
Spécifiez toujours la version de l’API
Ne vous fiez jamais à la version par défaut d’un fournisseur d’API. Spécifiez explicitement la version dans chaque appel d’API. En spécifiant explicitement la version, vous contrôlez la version que le script ou l’application exécute.
Centraliser la constante de version
Définissez la version de l’API comme une constante ou une variable de configuration unique et facilement localisable au début de votre script ou dans un fichier de configuration distinct. Cela permet de simplifier la résolution des problèmes et d’améliorer la maintenabilité. Exemple :
# config.py ou au début du script principal API_VERSION = ’2026-01-01’ # dans un appel à requests headers = { ’Accept’ : ’application/json’, ’Authorization’ : token, ’X-Version’ : API_VERSION, } resp = requests.get( ’https ://api.app.wdesk.com/spreadsheets’, headers = headers, ) Évitez de mélanger les versions d’API
N’essayez pas de mélanger les versions d’API au sein d’un même script ou d’une même application. Tous les appels d’API au sein d’un même script ou d’une même application doivent faire référence à la même version de l’API Workiva (par exemple, tous les appels d’API doivent utiliser la version « 2026-01-01 »). Le mélange des versions complique le débogage, les schémas de requête et les formats de réponse, ce qui rend le comportement du script imprévisible et la maintenance plus compliquée.
Isoler la logique d’interaction de l’API
Créez un module dédié ou un ensemble de fonctions (souvent appelé « wrapper » ou « client ») qui gère toutes les communications avec l’API externe. Ce modèle sépare la « logique commerciale » de votre script de la « logique de communication de l’API ». Si l’API change (par exemple, l’URL de l’extrémité ou la structure de la requête/réponse change dans une nouvelle version de l’API), seules les fonctions d’enveloppe doivent être mises à jour, et non le(s) script(s) tout(s) entier(s).
Traitez les points de terminaison et les paramètres obsolètes de manière appropriée
Lors de la migration d’une ancienne version de l’API vers une nouvelle, prévoyez que les points d’extrémité et les paramètres peuvent être renommés ou supprimés. Veillez à ce que votre script comprenne une gestion et une journalisation robustes des erreurs, afin de respecter les meilleures pratiques en matière de développement de scripts et d’augmenter la probabilité que les erreurs liées à la version soient détectées et journalisées.
Pour de plus amples informations sur les meilleures pratiques en matière de rédaction de scripts, consultez l’article Workiva Scripting : Development Best Practices .
Surveillez et planifiez l’obsolescence
Workiva passe à deux fenêtres de publication par an pour les nouvelles versions majeures, au printemps et à l’automne. Dans le cas où il n’y a pas de changement majeur à l’approche d’une date de publication et que le candidat à la publication pour cette période est vide, Workiva ne publiera pas de nouvelle version de l’API à ce moment-là.
Nous vous recommandons de suivre activement le site Web Workiva API Developer Hub, de vous abonner à Workiva Release Notes, et de suivre les calendriers de publication et de dépréciation publiés. Les scripts utilisant une version d’API obsolète finiront par tomber en panne. Connaître la date d’expiration (fin de vie) d’une version d’API vous permet de planifier les travaux de mise à niveau nécessaires avant la date d’expiration.
Migration et validation des scripts
Pour garantir une migration transparente des versions de l’API, établissez une stratégie de test parallèle : copiez le script de production existant, modifiez uniquement la copie pour cibler la nouvelle version de l’API (y compris toute modification nécessaire des en-têtes, du chemin d’accès à l’URL et/ou de la structure requête/réponse), puis testez à la fois l’ancien et le nouveau script pour comparer et vérifier les fonctionnalités et les résultats.
En les exécutant côte à côte dans un environnement contrôlé, vous pouvez utiliser l’ancien script stable comme norme pour contrôler et vérifier que les fonctionnalités et les résultats produits par le nouveau script sont identiques avant de passer entièrement à la nouvelle version et de supprimer l’ancienne version.