Faire évoluer une API sans la casser
La documentation d'une API décrit chaque adresse, chaque méthode, chaque champ et chaque erreur. Le versionnement permet de la changer sans casser les programmes qui l'utilisent.
Une API publiée est un contrat. Dès que d'autres écrivent du code autour d'elle, chaque modification peut leur coûter un jour de travail.
À la fin de cette leçon
Remarque
Je peux documenter une API et la modifier sans casser ses utilisateurs.
Mots clés
| Mot | Ce que ça veut dire | Exemple |
|---|---|---|
| Documentation | le texte qui explique comment appeler l'API | |
| Contrat | ce que l'API promet à ceux qui l'appellent | |
| Version | un numéro qui fige un contrat | v1 |
| Changement compatible | une modification après laquelle les anciens clients marchent encore | |
| Changement cassant | une modification qui oblige les clients à changer leur code | |
| Dépréciation | l'annonce qu'une fonction sera retirée plus tard |
Les cellules que les étudiants remplissent restent vides dans cet aperçu.
Une bonne documentation évite de deviner
Pour chaque adresse, la documentation donne la méthode, les paramètres, un exemple de requête, un exemple de réponse et les erreurs possibles.
Elle se périme vite si on l'écrit à la main. Beaucoup d'outils la produisent donc à partir du code ou de la base elle-même.
Le serveur du laboratoire se décrit lui-même
À sa racine, le serveur du laboratoire renvoie une description de toutes ses adresses, au format OpenAPI. Un outil peut la lire pour afficher une documentation.
Préparez le catalogue, puis cherchez l'adresse /livres dans cette description. Le Run de préparation peut être relancé pour repartir de zéro.
Créer la table des livres
PGPASSWORD=shop psql -q -h db -U shop -c "set client_min_messages to warning; drop table if exists livres; create table livres (id serial primary key, titre text not null unique, auteur text not null, annee integer not null, exemplaires integer not null default 1 check (exemplaires >= 0), disponible boolean not null default true, resume text); insert into livres (titre, auteur, annee, exemplaires, disponible) values ('Germinal', 'Emile Zola', 1885, 3, true), ('Candide', 'Voltaire', 1759, 0, false), ('Madame Bovary', 'Gustave Flaubert', 1857, 2, true), ('La Peste', 'Albert Camus', 1947, 4, true), ('Bel-Ami', 'Guy de Maupassant', 1885, 1, true); notify pgrst, 'reload schema'"Affichée ici, non exécutée. Créez un compte gratuit pour appuyer sur Exécuter et la saisir dans le terminal de votre propre labo.
Trouver l'adresse /livres dans la description
curl -s "http://api:3000/" | grep -o '"/livres"' | head -n 1Affichée ici, non exécutée. Créez un compte gratuit pour appuyer sur Exécuter et la saisir dans le terminal de votre propre labo.
Ajouter est compatible, retirer ne l'est pas
Un client écrit son code pour le contrat qu'il connaît. Un champ en plus dans la réponse ne le gêne pas : il l'ignore. Un champ en moins, ou renommé, le fait échouer.
Le tableau classe les changements les plus courants. Retenez la règle : ajouter est sûr, retirer ou changer ne l'est pas.
Exemple : quels changements cassent les clients
| Changement | Casse les clients ? | Pourquoi |
|---|---|---|
| Ajouter un champ à la réponse | Non | Les anciens clients l'ignorent |
| Ajouter une adresse | Non | Personne ne l'appelle encore |
| Rendre un champ de requête facultatif | Non | Les anciennes requêtes restent valides |
| Retirer un champ de la réponse | Oui | Un client le lit et ne le trouve plus |
| Renommer un champ | Oui | C'est retirer un nom et en ajouter un autre |
| Changer le type d'un champ | Oui | Le client lit un texte là où il attend un nombre |
| Rendre un champ de requête obligatoire | Oui | Les anciennes requêtes sont refusées |
Les cellules que les étudiants remplissent restent vides dans cet aperçu.
Voir un changement cassant dans le laboratoire
Le catalogue sert d'API. Un client demande les colonnes titre et annee. D'abord vous ajoutez une colonne : ce client marche encore. Puis vous renommez annee : il casse.
Chaque Run de requête n'affiche que le code de statut. Lancez-les dans l'ordre.
Ajouter la colonne isbn
PGPASSWORD=shop psql -q -h db -U shop -c "alter table livres add column isbn text; notify pgrst, 'reload schema'"Affichée ici, non exécutée. Créez un compte gratuit pour appuyer sur Exécuter et la saisir dans le terminal de votre propre labo.
Le client demande titre et annee
curl -s -o /dev/null -w "%{http_code}\n" "http://api:3000/livres?select=titre,annee"Affichée ici, non exécutée. Créez un compte gratuit pour appuyer sur Exécuter et la saisir dans le terminal de votre propre labo.
Renommer la colonne annee
PGPASSWORD=shop psql -q -h db -U shop -c "alter table livres rename column annee to annee_publication; notify pgrst, 'reload schema'"Affichée ici, non exécutée. Créez un compte gratuit pour appuyer sur Exécuter et la saisir dans le terminal de votre propre labo.
Le même client, après le renommage
curl -s -o /dev/null -w "%{http_code}\n" "http://api:3000/livres?select=titre,annee"Affichée ici, non exécutée. Créez un compte gratuit pour appuyer sur Exécuter et la saisir dans le terminal de votre propre labo.
Remettre le nom de la colonne
PGPASSWORD=shop psql -q -h db -U shop -c "alter table livres rename column annee_publication to annee; notify pgrst, 'reload schema'"Affichée ici, non exécutée. Créez un compte gratuit pour appuyer sur Exécuter et la saisir dans le terminal de votre propre labo.
Une erreur fréquente
Attention
Beaucoup pensent que renommer un champ pour plus de clarté est un simple nettoyage. Faux : chaque client qui lisait l'ancien nom échoue. Ajoutez le nouveau nom, gardez l'ancien un temps, annoncez son retrait, puis retirez-le.
Une version protège les anciens clients
Quand un changement cassant est inévitable, on publie une nouvelle version à côté de l'ancienne. Le numéro se met souvent dans l'adresse : /v1/livres et /v2/livres.
On annonce ensuite la dépréciation de l'ancienne, avec une date. Les clients ont le temps de migrer. L'ancienne version n'est retirée qu'après.