Accueil › Node.js › Versions et compatibilité
Versions et compatibilité
Concevoir une API RESTdebutant
Une API publiée ne se change plus. Dès qu'un client que vous ne contrôlez pas l'appelle, chaque champ est un engagement — y compris les champs que vous avez exposés sans y penser.
La frontière
| Changement | Compatible |
|---|---|
| Ajouter un champ dans la réponse | oui |
| Ajouter un paramètre optionnel | oui |
| Ajouter une route | oui |
| Retirer ou renommer un champ | non |
| Changer le type d'un champ | non |
| Rendre un paramètre obligatoire | non |
| Restreindre une valeur acceptée | non |
La règle tient en une phrase : les ajouts passent, les retraits et les resserrements cassent.
Le changement de type est le plus sournois
// Avant : { "montant": 10 } Après : { "montant": "10" }
reponse.montant * 2 // 20 — ça marche encore
reponse.montant + 1 // "101" — faux, sans aucune erreur
Aucune exception, aucune trace dans un journal, un montant faux à l'écran. La panne n'apparaît pas là où le changement a eu lieu.
Quand le retrait est inévitable
/v1/commandes → maintenue
/v2/commandes → nouvelle forme
Le versionnement dans l'URL n'est pas le plus élégant — une même ressource a
deux adresses. C'est le plus simple à exploiter : visible dans un journal, dans
un curl de dépannage, routable vers deux déploiements distincts.
app.use("/v1", routeurV1);
app.use("/v2", routeurV2);
Les termes à connaître
- Changement compatible
Un ajout qu'un client existant peut ignorer — un champ de plus dans une réponse, un paramètre optionnel, une nouvelle valeur d'énumération déjà prévue.
- Changement incompatible
Un retrait, un renommage, un changement de type, ou une nouvelle exigence sur une requête. Il casse du code qui fonctionnait.
- Versionnement par URL
/v1/commandes. Visible dans un journal, dans uncurl, dans un routeur — pas élégant, et le plus simple à exploiter.- Versionnement par en-tête
Un en-tête
AcceptouAPI-Version. Plus conforme à l'esprit HTTP, invisible dans une URL partagée, et plus facile à oublier côté client.- Dépréciation
Annoncer qu'un champ ou une version disparaîtra, avec une date. Un en-tête
Deprecationet un journal d'usage valent mieux qu'un courriel.- Tolérance du lecteur
Un client bien écrit ignore les champs qu'il ne connaît pas. C'est ce qui rend tout ajout compatible — et ce qu'on ne peut pas garantir chez autrui.
- Champ interne exposé
Une colonne de base renvoyée sans décision explicite. Elle devient un contrat qu'on ne peut plus retirer, pour l'avoir publiée par inadvertance.
Cette page présente la partie essentielle de la leçon. Les exemples commentés, les pièges courants et les trois questions de quiz sont dans l'application.