Formations — 1 037 leçons en français

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 un curl, dans un routeur — pas élégant, et le plus simple à exploiter.

Versionnement par en-tête

Un en-tête Accept ou API-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 Deprecation et 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.

Lire l'explication détaillée et faire le quiz →

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.