L'application qui ne voit jamais la base
Un chauffeur-livreur consulte ses colis sur son téléphone. L'application ne se connecte pas à la base de données.
Elle envoie une requête web à un petit serveur. Le serveur lance la requête SQL et renvoie les lignes.
Ce serveur est une API web. Presque toutes les applications que vous utilisez parlent à leurs données ainsi.
À la fin de cette leçon
Remarque
Je peux lire et écrire des lignes de base de données par HTTP.
Mots clés
| Mot | Ce que ça veut dire | Exemple |
|---|---|---|
| API | un moyen pour un programme de demander des données à un autre | |
| Point d'accès | l'adresse web d'une table ou d'une action | /livraisons |
| Méthode HTTP | le verbe d'une requête : lire, ajouter, changer ou retirer | GET |
| JSON | un texte qui écrit des lignes en listes et en paires nom-valeur | |
| Code de statut | un nombre qui dit comment la requête s'est passée | 404 |
| Filtre | un test dans l'adresse qui choisit les lignes renvoyées | statut=eq.livree |
Les cellules que les étudiants remplissent restent vides dans cet aperçu.
Une API met une table sur le web
Dans ce laboratoire, un outil nommé PostgREST transforme chaque table en adresse web. /livraisons est la table livraisons.
Vous envoyez une requête avec curl. Le serveur répond par des lignes écrites en JSON : une liste entre crochets, chaque ligne entre accolades.
Créez d'abord une table avec psql, le client de la base. Lancez ces Runs dans l'ordre.
Donner le mot de passe à psql
export PGPASSWORD=shopAffiché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.
Repartir de zéro
psql -h db -U shop -c "drop table if exists livraisons"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.
Créer la table livraisons
psql -h db -U shop -c "create table livraisons (id serial primary key, destinataire text not null, statut text not null default 'en_attente', poids_kg numeric(6,2) not null)"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 quatre livraisons
psql -h db -U shop -c "insert into livraisons (destinataire, statut, poids_kg) values ('Atelier Roche', 'en_attente', 12.50), ('Cabinet Leroy', 'en_attente', 2.40), ('Boulangerie Martin', 'livree', 30), ('Epicerie Sud', 'en_attente', 7.25)"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.
Dire à l'API de relire la base
psql -h db -U shop -c "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 toute la table
curl -s -w "\n" "http://api:3000/livraisons?order=id"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.
L'adresse dit quelles lignes vous voulez
Tout ce qui suit le ? est un filtre, comme un WHERE. statut=eq.en_attente veut dire : statut égal à en_attente. poids_kg=gte.5 veut dire : 5 ou plus.
select=id,destinataire choisit les colonnes. order=poids_kg.desc trie. limit=2 coupe la liste. Reliez-les avec &.
Mettez l'adresse entière entre guillemets, sinon le shell lit le &.
Seulement les colis en attente
curl -s -w "\n" "http://api:3000/livraisons?statut=eq.en_attente&order=id"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.
Deux colonnes, colis de 5 kg ou plus
curl -s -w "\n" "http://api:3000/livraisons?poids_kg=gte.5&select=id,destinataire&order=id"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.
Les deux colis les plus lourds
curl -s -w "\n" "http://api:3000/livraisons?order=poids_kg.desc,id&limit=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.
Exemple : SQL et HTTP côte à côte
| SQL | Méthode HTTP | Adresse et corps |
|---|---|---|
| SELECT ... WHERE | GET | /livraisons?statut=eq.en_attente |
| INSERT INTO | POST | /livraisons, avec la nouvelle ligne en JSON |
| UPDATE ... WHERE | PATCH | /livraisons?id=eq.1, avec les changements en JSON |
| DELETE ... WHERE | DELETE | /livraisons?id=eq.3 |
Les cellules que les étudiants remplissent restent vides dans cet aperçu.
POST, PATCH et DELETE changent les données
Pour ajouter une ligne, envoyez-la en JSON avec POST. Pour changer des lignes, envoyez les changements avec PATCH. Pour en retirer, envoyez DELETE.
Comme en SQL, le filtre de l'adresse décide des lignes touchées. Un PATCH ou un DELETE sans filtre toucherait toutes les lignes.
Le serveur dit comment cela s'est passé avec un code de statut.
Ajouter un colis et le relire
curl -s -w "\n" -X POST -H "Content-Type: application/json" -H "Prefer: return=representation" -d '{"destinataire":"Mairie de Nantes","poids_kg":4.5}' "http://api:3000/livraisons"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.
Marquer le colis 1 comme livré
curl -s -o /dev/null -w "%{http_code}\n" -X PATCH -H "Content-Type: application/json" -d '{"statut":"livree"}' "http://api:3000/livraisons?id=eq.1"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 un colis qui n'existe pas
curl -s -o /dev/null -w "%{http_code}\n" -X PATCH -H "Content-Type: application/json" -d '{"statut":"livree"}' "http://api:3000/livraisons?id=eq.999"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'un code 2xx prouve que la requête a fait ce qu'on voulait. Le code dit seulement que le serveur a compris et accepté. Un PATCH dont le filtre ne trouve rien répond quand même 204. Relisez la table pour vérifier.
Supprimer le colis 3
curl -s -o /dev/null -w "%{http_code}\n" -X DELETE "http://api:3000/livraisons?id=eq.3"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.
Relire la table après les changements
curl -s -w "\n" "http://api:3000/livraisons?order=id"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 ligne que la base refuse
curl -s -w "\n%{http_code}\n" -X POST -H "Content-Type: application/json" -d '{"poids_kg":1}' "http://api:3000/livraisons"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 qui n'existe pas
curl -s -w "\n%{http_code}\n" "http://api:3000/rien"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.
Exemple : lire les codes de statut
| Code | Sens | Vu dans cette leçon |
|---|---|---|
| 200 | Voici les lignes | La lecture de la table |
| 201 | Une ligne a été créée | Un POST qui ne demande pas la ligne en retour |
| 204 | Fait, rien à renvoyer | Le PATCH et le DELETE |
| 400 | La requête est fausse ou viole une règle | Le colis sans destinataire |
| 404 | Aucune table ou adresse de ce nom | La demande de /rien |
Les cellules que les étudiants remplissent restent vides dans cet aperçu.