Une nécessité : repenser nos API pour gagner en cohérence et en performance
Pendant longtemps, nos API ont évolué au fil de l’eau, portées par les besoins internes et les contraintes rencontrées. Mais en l’absence de normalisation, elles ont accumulé incohérences et limitations, rendant parfois leur utilisation contraignante.
À un certain stade, leur amélioration est devenue incontournable. Pour des raisons de cohérence, de qualité technique, de maintenabilité, mais aussi de crédibilité vis-à-vis de nos futurs clients.
Phoenix : une refonte de notre application LetReco
C’est dans ce contexte qu’est né Phoenix, la refonte de notre application Letreco. Cette refonte dispose d’APIs v2, qui reprend l’ensemble des fonctionnalités de l’ancienne version et en ajoute de nouvelles tout en offrant une meilleure stabilité et des performances techniques nettement améliorées.
Des améliorations mais des impacts inattendus
Mais le passage du build au run s’est avéré challengeant. Certaines évolutions, considérées comme sans impactes avant le début run, ont provoqué des effets secondaires.
Ces améliorations étaient nécessaires, mais leurs conséquences sur l’écosystème existant ont été, dans certains cas, sous-estimées.
Cette tension entre progrès technique et continuité de service est vite devenue un enjeu central pour les équipes tech.
Le dilemme : innover sans déstabiliser
Modifier une API n’est jamais anodin.
Une vision technique vs une réalité client
- Pour l’équipe technique, c’est une avancée : on homogénéise, on corrige les imperfections, on prépare l’avenir.
- Pour le client, cela peut s’apparenter à une régression brutale : un champ qui disparaît, une route modifiée, et l’intégration cesse de fonctionner.
Trois piliers pour limiter les frictions
L’enjeu n’est pas de renoncer aux évolutions, mais de trouver un équilibre. Nous devons faire évoluer les API de manière continue tout en réduisant les frictions, en assurant transparence et accompagnement.
Concrètement, cela se traduit par :
1.Une détection proactive des changements,
2.Un processus d’arbitrage clair,
3.Une communication adaptée vers l’extérieur
Un workflow GitHub pour mieux anticiper
Trop souvent, nous ne mesurions pas précisément l’impact des modifications faute d’outil automatique.
Pour y remédier, un workflow GitHub a été mis en place pour surveiller la compatibilité des API et casser les merges en cas de problèmes afin d’éviter des erreurs en production.
Comment fonctionne le workflow ?
Lorsqu’une merge request est ouverte, un workflow s’exécute et génère :
- Les spécifications OpenAPI de la branche en cours et de la branche cible,
- Puis compare les deux.
- Si des différences sont détectées, elles sont signalées avec différents niveaux de criticité :
- Informations (changements mineurs)
- Avertissements
- Erreurs (changements susceptibles de rompre la compatibilité)
Un rapport HTML détaille les résultats, listant les API impactées et la nature des évolutions. Par exemple, le renommage d’un champ firstName en firstNames est immédiatement identifié comme une modification à risque.
Ce workflow n’est pas bloquant : il n’empêche pas la fusion. Mais il informe le relecteur. A lui d’arbitrer : faut-il valider ? Informer ? Revoir la modification ?
Ce workflow ne détecte pas une erreur de programmation mais une erreur fonctionnelle.
Techniquement
Api compatibility
Ce workflow vérifie la compatibilité entre la spécification OpenAPI de la branche develop et celle de la branche courante (ou d’une PR), afin de détecter les changements et les régressions dans l’API. Ce trigger sur chaque pull request effectue les actions suivantes :
build_develop_api_spec
- Objectif : Générer ou récupérer la spécification OpenAPI de la branche develop.
- Étapes : Construire la spécification (swagger.yaml) pour la branche develop.
build_new_api_spec
- Objectif : Générer ou récupérer la spécification OpenAPI de la branche courante ou PR.
- Étapes : Construire la spécification (swagger.yaml) pour la branche courante.
compare_swagger_files
- Dépendances : Doit attendre que build_develop_api_spec et build_new_api_spec soient terminés (needs).
- Objectif : Comparer les deux spécifications pour détecter les changements et les incompatibilités.
- Environnement : ubuntu-latest
Exemple de fichier Yaml :
– name: Download new swagger file
uses: actions/download-artifact@v4
with:
name: new_swagger_file
path: new
– name: Download develop swagger file
uses: actions/download-artifact@v4
with:
name: develop_swagger_file
path: develop
– name: Install oasdiff
run: |
curl -sSL https://github.com/oasdiff/oasdiff/releases/download/v1.11.7/oasdiff_1.11.7_linux_amd64.tar.gz \
| tar -xz oasdiff
sudo mv oasdiff /usr/local/bin/
– name: Run oasdiff changelog
run: |
mkdir -p diff-report
# Rapport complet Markdown
oasdiff changelog -f html develop/swagger.yaml new/swagger.yaml > diff-report/changelog.html
– name: Upload diff changelog
uses: actions/upload-artifact@v4
with:
name: openapi-diff-changelot
path: diff-report/changelog.html
– name: Run oasdiff breaking
run: |
# Breaking changes (fail si incompatible)
oasdiff breaking -f html develop/swagger.yaml new/swagger.yaml > diff-report/breaking.html
Derrière l’outil, un processus d’arbitrage humain et collégial
L’outil est un indicateur et ne remplace pas l’expertise humaine. La décision finale relève d’un processus collégial.
Le rôle du comité de changement
Aujourd’hui, l’arbitrage s’organise en deux temps via un comité de changement :
- L’ingénieur qui effectue la revue analyse les alertes et évalue l’impact sur la compatibilité.
- En cas de doute, le CTO arbitre et centralise les décisions.
Ce comité inclut plusieurs parties prenantes :
- La Scrum Mistress, qui connait les usages clients en profondeur.
- Le responsable des audits, garant de la traçabilité et de la conformité.
- L’auteur de ces lignes, responsable de la mise en production.
- L’équipe produit, qui arbitre la valeur métier.
Ainsi, une modification peut être validée si elle apporte une amélioration substantielle, mais toujours après évaluation du nombre de clients affectés, du coût de correction côté client, et de la nécessité d’une communication spécifique.
Cette dimension humaine est essentielle. Au-delà du code, il faut préserver la relation de confiance avec nos utilisateurs.
La communication : une brique essentielle de la confiance client
Versionner, déprécier, prévenir
Modifier une API sans prévenir c’est risquer de désorienter les clients. Pour éviter cela, nous nous engageons à adopter des pratiques responsables :
- Versionner nos API (V2, V2.1, etc.).
- Déprécier les anciennes routes avant suppression.
- Communiquer en amont avec nos clients pour leur permettre d’adapter leurs intégrations.
Un effort transversal
Ce travail ne repose pas uniquement sur l’équipe tech. Il mobilise aussi :
- Le support client
- Le marketing
- La relation client.
Car une API constitue une promesse de stabilité. Et une promesse non tenue met en péril notre crédibilité.
Vers une maturité accrue
Les progrès réalisés vont dans la bonne direction. Le workflow GitHub fournit une visibilité sur les impacts. Nous disposons d’un processus d’arbitrage. Nous avons commencé à mettre en place des garde-fous (logs, handlers, audits).
Les prochaines étapes
- Formaliser un processus de versioning (dépréciation → suppression).
- Intégrer davantage la communication client.
- Affiner le workflow pour distinguer différents types de changements (ex : un simple renommage de champ).
Conclusion : faire évoluer nos API tout en renforçant la confiance
Faire évoluer une API est indispensable. Mais chaque changement doit être évalué au regard de la stabilité promise à nos clients.
Grâce au workflow GitHub, nous disposons d’un outil de détection efficace. Grâce à un processus d’arbitrage collégial, nous avons la gouvernance nécessaire.
Demain, nous irons plus loin : en renforçant la communication, en mettant en place des pratiques matures de versioning et de dépréciation.
L’enjeu est clair : progresser techniquement tout en consolidant la confiance des clients. Cet équilibre est la condition de la croissance durable de Phoenix.
Les auteurs de cet article :
Rochdi HAMDI, Lead DevOps chez LetReco
Je veille au déploiement et à la supervision de nos applications critiques, comme LetReco, qui traite plus d’un million de lettres recommandées électroniques par mois. Mon quotidien : anticiper les risques, sécuriser nos déploiements cloud et garantir que notre CI/CD fonctionne sans heurts, même quand la mer devient agitée.
Abdelmouheimen TRABELSI, Architecte technique chez LetReco
Je me concentre principalement sur le développement de LetReco. Avec une expérience en logistique, je veille à la sécurité applicative et à la fiabilité des systèmes SaaS, en garantissant robustesse et agilité pour tester rapidement de nouvelles solutions. Comme sur un terrain de foot, je repousse sans cesse mes limites pour anticiper les imprévus.