Rédiger la documentation API dans Excel ou en PDF et la partager par e-mail est une pratique bien trop familière.
Quand un problème survient, on contacte la personne en charge, on fouille dans les anciens e-mails pour vérifier la version du document détenue par le client. On réexplique les changements, on renvoie le document corrigé, puis on vérifie encore s’il a bien été pris en compte.
À force de répéter ce processus, nous avons fini par penser qu’il s’agissait du travail normalement nécessaire.
Mais le problème ne s’arrête pas à un seul document erroné.
À chaque modification de l’API, de nouveaux fichiers et e-mails, des exceptions propres à chaque client et les souvenirs des personnes responsables s’accumulent. Au départ, ce n’est qu’un petit désagrément, mais avec le temps il devient difficile de savoir quel document fait foi, et le nombre de personnes et le temps nécessaires pour résoudre les problèmes augmentent eux aussi.
Si un client développe sur l’ancien format de requête, cela entraîne des erreurs d’intégration et du travail de reprise. Si des champs obligatoires ou le mode d’authentification sont transmis différemment, le calendrier de développement prend du retard et, si l’API est déjà en production, cela peut même conduire à des erreurs de données ou à une panne.
Ce n’est qu’après l’apparition du problème qu’on découvre que l’équipe de développement interne et le client regardaient des documents différents.
À partir de là, les développeurs interrompent leur travail en cours pour identifier la cause. Les équipes d’exploitation recherchent les anciens documents et l’historique des échanges, et le client revérifie son implémentation ainsi que les spécifications reçues. Un seul écart entre deux versions d’un document peut bloquer simultanément le travail de plusieurs personnes.
Et pourtant, la plupart de ces problèmes se règlent discrètement par téléphone, e-mail ou messagerie.
Quelqu’un renvoie le fichier corrigé, quelqu’un d’autre explique la situation au client, et les développeurs ajoutent en urgence un traitement d’exception. Le problème immédiat est résolu, mais l’organisation ne conserve pas pourquoi il est survenu, quels clients ont été touchés, ni ce qui a été modifié pour éviter qu’il se reproduise.
Le temps consacré à ce processus est du temps qui aurait dû servir au développement et à l’amélioration du produit.
Le problème plus grave encore, c’est que tout ce processus dépend de l’expérience, de la mémoire et de la boîte mail d’une personne précise. Si cette personne est absente ou quitte l’entreprise, l’organisation doit fouiller les e-mails et l’historique des messageries pour reconstituer le travail.
Une documentation API non gérée ne disparaît pas. Elle reste à l’intérieur comme à l’extérieur de l’organisation et devient une dette documentaire invisible.
Il est possible que nous ne soyons pas réellement en train de résoudre le problème, mais simplement habitués à une manière de contenir chaque incident avec du temps humain lorsqu’il survient.
Ayant rencontré ce problème dans le travail réel, j’ai créé SpecBridge.
SpecBridge n’est pas simplement un outil pour rédiger de la documentation API. C’est un outil d’exploitation de documentation API qui permet de revoir les modifications des documents et de ne diffuser aux clients et partenaires externes que les versions approuvées.
Il ne remplace pas Swagger, mais importe Swagger/OpenAPI et les Postman Collections, puis se concentre sur la gestion des problèmes qui surviennent lors du partage vers l’extérieur.
- Comparaison des différences entre la version actuellement publiée et la version modifiée
- Revue et approbation des changements
- Séparation entre le brouillon et la version publiée vue par le client
- Gestion du périmètre de visibilité des documents selon chaque client
- Définition d’un mot de passe et d’une date d’expiration pour les liens publics
- Mise à disposition de la dernière documentation approuvée via un même lien
Il n’est plus nécessaire d’envoyer un nouveau fichier au client à chaque fois : seuls les documents validés en interne peuvent être redéployés sur le lien existant.
Les développeurs peuvent réduire les tâches répétitives consistant à retrouver puis renvoyer les documents, et l’organisation peut gérer la documentation API non plus selon la mémoire d’une personne, mais à partir d’un historique des changements enregistré et de critères de diffusion.
Nous recherchons actuellement des partenaires qui utilisent réellement SpecBridge pour exploiter leur documentation API et nous donner un retour honnête.
Si votre équipe gère sa documentation API dans Excel ou en PDF, ou renvoie la documentation à ses clients à chaque changement d’API, nous aimerions commencer par examiner ensemble un seul document que vous utilisez actuellement.
Plus que des compliments sur une fonctionnalité bien conçue, nous voulons entendre des avis sincères sur les points gênants en exploitation réelle, les procédures inutiles et les fonctionnalités manquantes.
Aucun commentaire pour le moment.