À quoi servent les codes de statut HTTP ?
Un code de statut HTTP est un nombre à trois chiffres. Le serveur le place en tête de sa réponse pour dire comment la requête s'est passée. Bien le choisir, avec un message d'erreur clair, permet au programme qui appelle l'API de réagir sans deviner.
Le premier chiffre donne la famille : 2 pour un succès, 4 pour une faute du client, 5 pour une panne du serveur.
À la fin de cette leçon
Remarque
Je peux choisir le bon code de statut et expliquer une erreur clairement.
Mots clés
| Mot | Ce que ça veut dire | Exemple |
|---|---|---|
| Code de statut | le nombre à trois chiffres qui ouvre la réponse | 404 |
| Famille | le premier chiffre du code, qui donne le genre de résultat | |
| Erreur du client | une requête fausse, signalée par un code en 4xx | |
| Erreur du serveur | une panne de l'autre côté, signalée par un code en 5xx | |
| Corps d'erreur | le JSON qui explique ce qui a échoué | |
| Contrainte | une règle que la base impose à une donnée | NOT NULL |
Les cellules que les étudiants remplissent restent vides dans cet aperçu.
Le premier chiffre donne la famille
Un programme lit le code avant le corps. Le premier chiffre lui suffit pour décider quoi faire.
Un code en 2xx veut dire que tout va bien. Un code en 4xx veut dire que la requête est fausse : la corriger avant de réessayer. Un code en 5xx veut dire que le serveur a échoué : réessayer plus tard peut marcher.
Exemple : les codes à connaître
| Code | Sens | Quand l'utiliser |
|---|---|---|
| 200 | Voici ce que vous demandez | Une lecture réussie |
| 201 | Une ressource a été créée | Un ajout réussi |
| 204 | Fait, rien à renvoyer | Un changement ou une suppression réussis |
| 400 | La requête est fausse | Une donnée invalide ou un champ manquant |
| 401 | Vous n'êtes pas identifié | Pas de clé ou de jeton valide |
| 403 | Vous n'en avez pas le droit | Identifié, mais interdit |
| 404 | Introuvable | Une adresse ou une ressource qui n'existe pas |
| 409 | Conflit avec l'état actuel | Un titre déjà pris |
| 429 | Trop de requêtes | La limite de débit est dépassée |
| 500 | Le serveur a échoué | Une panne ou un bogue |
Les cellules que les étudiants remplissent restent vides dans cet aperçu.
Préparer le catalogue et lire trois codes
Préparez la table livres. Le Run peut être relancé pour repartir de zéro.
Chaque Run suivant garde seulement le code de statut. Lancez-les dans l'ordre : lire, ajouter Nana, puis changer un livre.
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.
Lire les livres
curl -s -o /dev/null -w "%{http_code}\n" "http://api:3000/livres"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.
Ajouter le livre Nana
curl -s -o /dev/null -w "%{http_code}\n" -X POST -H "Content-Type: application/json" -d '{"titre":"Nana","auteur":"Emile Zola","annee":1880}' "http://api:3000/livres"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.
Changer le nombre d'exemplaires
curl -s -o /dev/null -w "%{http_code}\n" -X PATCH -H "Content-Type: application/json" -d '{"exemplaires":5}' "http://api:3000/livres?id=eq.2"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.
Chaque erreur a son code
Trois erreurs du client se ressemblent. Une donnée mal formée donne 400. Une ressource ou une adresse qui n'existe pas donne 404. Une donnée qui entre en conflit avec ce qui existe déjà donne 409.
Essayez les trois. Le conflit vient du titre de Nana, qui est déjà dans la table.
Ajouter un livre sans titre
curl -s -o /dev/null -w "%{http_code}\n" -X POST -H "Content-Type: application/json" -d '{"auteur":"X","annee":1900}' "http://api:3000/livres"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.
Demander une table inconnue
curl -s -o /dev/null -w "%{http_code}\n" "http://api:3000/rayons"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.
Ajouter Nana une seconde fois
curl -s -o /dev/null -w "%{http_code}\n" -X POST -H "Content-Type: application/json" -d '{"titre":"Nana","auteur":"Emile Zola","annee":1880}' "http://api:3000/livres"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 qu'on peut répondre 200 à tout et mettre le mot erreur dans le corps. Faux : un programme lit le code avant le corps, donc un 200 qui cache une erreur passe pour un succès. Le code doit dire la vérité.
Un corps d'erreur explique le problème
Le code dit la famille de l'échec. Le corps dit pourquoi. Un bon corps d'erreur contient un code court que le programme compare, un message que la personne lit, et si possible un détail.
Le serveur du laboratoire renvoie le message de la base elle-même. Lisez-le pour l'ajout sans titre.
Lire le corps de l'erreur
curl -s -X POST -H "Content-Type: application/json" -d '{"auteur":"X","annee":1900}' "http://api:3000/livres" -w "\n"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.
Ne garder que le code d'erreur
curl -s -X POST -H "Content-Type: application/json" -d '{"auteur":"X","annee":1900}' "http://api:3000/livres" | grep -o '"code":"[0-9A-Z]*"'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.