API : faire évoluer sans casser vos intégrations
Le jour où un partenaire consomme votre API, sa forme cesse de vous appartenir. La question n’est plus « comment la rendre meilleure ? » mais « comment la faire évoluer sans casser ce qui tourne ailleurs ? ».
Équipe RGAIX · · 7 min de lecture
Distinguer les changements compatibles des autres
La règle est simple à énoncer : ajouter est compatible, retirer et renommer ne le sont pas. Ce qui la rend difficile à appliquer, ce sont les cas intermédiaires que l’on croit inoffensifs.
| Changement | Compatible ? | Pourquoi |
|---|---|---|
| Ajouter un champ optionnel | Oui | Les clients ignorent ce qu’ils ne connaissent pas |
| Rendre un champ obligatoire | Non | Casse les appels existants |
| Ajouter une valeur d’énumération | Rarement | Les clients stricts rejettent l’inconnu |
| Élargir un type numérique | Attention | Débordements côté client |
| Changer l’ordre d’une liste | Attention | Certains clients s’appuient dessus |
La troisième ligne est la plus sous-estimée : ajouter un nouveau statut à une énumération casse tous les clients qui valident strictement les valeurs reçues. C’est un ajout, et pourtant c’est une rupture.
Documenter ce qui n’est pas garanti
Un contrat d’API doit dire ce sur quoi on peut s’appuyer, mais surtout ce sur quoi on ne peut pas : l’ordre des champs, la forme exacte des identifiants, la présence de champs non documentés, la stabilité des messages d’erreur en langage naturel.
Sans cette liste, chaque détail observé devient une garantie implicite. Les intégrateurs s’appuient sur ce qu’ils voient, pas sur ce que vous aviez l’intention de promettre.
Versionner le moins possible
Une nouvelle version majeure double le coût de maintenance et oblige chaque partenaire à planifier une migration. Réservez-la aux ruptures inévitables, et préférez l’ajout de champs, la dépréciation progressive et les valeurs par défaut.
- Ajouter le nouveau champ à côté de l’ancien, sans rien supprimer.
- Annoncer la dépréciation avec une date, dans la documentation et dans un en-tête de réponse.
- Mesurer qui utilise encore l’ancien champ, en journalisant les appels.
- Prévenir individuellement les derniers utilisateurs avant le retrait.
Rendre les erreurs exploitables
Une intégration se casse plus souvent sur la gestion des erreurs que sur le cas nominal. Un code stable et lisible par une machine, un message en langage naturel pour l’humain, et un identifiant de corrélation pour retrouver l’appel dans vos journaux : ces trois éléments évitent la plupart des allers-retours.
Précisez aussi ce qui est rejouable. Un partenaire qui ne sait pas si sa requête a été prise en compte réessaiera — et créera un doublon si vous n’avez pas prévu de clé d’idempotence.
Une API est une promesse tenue dans le temps. Ce qui la rend fiable n’est pas son élégance, mais la prévisibilité de ses changements.
Pages liées
Développement web & mobile
Des logiciels au service de vos métiers.
Découvrir l’offre ↗À LIRE ENSUITEReprendre un projet existant : les dix vérifications d’entrée
Avant d’écrire la première ligne, dix contrôles disent si la reprise est faisable, coûteuse ou impossible en l’état.
Lire l’article ↗À LIRE ENSUITERéponse à incident : collecter les preuves avant de nettoyer
Nettoyer un serveur compromis sans chercher le vecteur garantit de recommencer. L’ordre des gestes compte plus que leur rapidité.
Lire l’article ↗Parlons de ce qui vous bloque.
Une urgence, un profil à trouver ou un projet à structurer : commençons par votre besoin.