Qu'est-ce qu'une API REST ?
Une API REST (REpresentational State Transfer) donne accès à des ressources, comme des livres ou des emprunts, par des adresses claires et quelques méthodes HTTP. Bien choisir ces adresses et ces méthodes rend une API facile à deviner et à utiliser.
Un développeur qui découvre l'API d'une bibliothèque devrait trouver l'adresse d'un livre sans lire un manuel entier.
À la fin de cette leçon
Remarque
Je peux choisir l'adresse et la méthode qui conviennent à une action.
Mots clés
| Mot | Ce que ça veut dire | Exemple |
|---|---|---|
| Ressource | une chose que l'API fait connaître | un livre |
| Collection | l'ensemble des ressources de même sorte | /livres |
| Point d'accès | l'adresse à laquelle on envoie une requête | |
| Méthode sûre | une méthode qui lit sans rien changer | GET |
| Méthode idempotente | une méthode qu'on peut répéter sans changer le résultat final | |
| Filtre | la partie de l'adresse après le point d'interrogation, qui choisit les lignes | ?id=eq.3 |
Les cellules que les étudiants remplissent restent vides dans cet aperçu.
L'adresse nomme la chose, la méthode agit
Dans une API REST, l'adresse désigne une chose, jamais une action. On écrit /livres et non /ajouterUnLivre. Le nom est au pluriel, car c'est la collection.
Ce que vous voulez faire de cette chose, c'est la méthode HTTP qui le dit. Une même adresse sert donc à lire, ajouter ou supprimer.
Exemple : de l'action à la requête
| Action voulue | Adresse à éviter | Requête REST |
|---|---|---|
| Lister les livres | /listerLivres | GET /livres |
| Lire le livre 3 | /lireLivre?num=3 | GET /livres?id=eq.3 |
| Ajouter un livre | /ajouterLivre | POST /livres |
| Supprimer le livre 3 | /supprimerLivre?num=3 | DELETE /livres?id=eq.3 |
Les cellules que les étudiants remplissent restent vides dans cet aperçu.
Une ligne se désigne par un filtre
Beaucoup d'API écrivent /livres/3 pour le livre numéro 3. Le serveur du laboratoire utilise un filtre : /livres?id=eq.3. Les deux disent la même chose : la ressource de numéro 3 dans la collection livres.
Préparez d'abord le catalogue. Le Run recrée la table, et 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.
Lire le livre numéro 3
curl -s -w "\n" "http://api:3000/livres?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.
Chaque méthode a un rôle précis
GET lit. POST ajoute. PUT remplace une ligne entière. PATCH change seulement quelques champs. DELETE retire.
Deux mots comptent pour un concepteur. Une méthode sûre ne change rien. Une méthode idempotente peut être répétée : le résultat final est le même, que vous l'envoyiez une fois ou trois.
Exemple : les cinq méthodes
| Méthode | Rôle | Sûre | Idempotente |
|---|---|---|---|
| GET | Lire | Oui | Oui |
| POST | Ajouter une ligne | Non | Non |
| PUT | Remplacer une ligne entière | Non | Oui |
| PATCH | Changer quelques champs | Non | Pas toujours |
| DELETE | Retirer | Non | Oui |
Les cellules que les étudiants remplissent restent vides dans cet aperçu.
Répéter une requête change parfois le résultat
Le titre d'un livre est unique dans la table. Un POST qui ajoute Nana réussit la première fois. La seconde fois, le titre existe déjà et le serveur refuse.
Un DELETE se comporte autrement. Après le premier, Nana a disparu. Le second ne change plus rien. Lancez chaque Run deux fois et comparez les codes.
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.
Supprimer le livre Nana
curl -s -o /dev/null -w "%{http_code}\n" -X DELETE "http://api:3000/livres?titre=eq.Nana"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 POST convient à toute action, puisqu'il marche toujours. C'est faux : POST n'est ni sûr ni répétable, donc un client qui réessaie après une panne peut ajouter deux fois. Choisissez la méthode qui dit l'action.
Une adresse peut aussi filtrer, trier et limiter
Après le ?, chaque filtre a la forme colonne=opérateur.valeur. gte veut dire « plus grand ou égal » et lt « plus petit que ». On les relie avec &.
select=titre,annee choisit les colonnes. order=annee,id trie. limit=2 coupe la liste. Mettez l'adresse entre guillemets, sinon le shell lit le &.
Les livres parus depuis 1860
curl -s -w "\n" "http://api:3000/livres?annee=gte.1860&select=titre,annee&order=annee,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.
Compter les livres d'avant 1900
curl -s "http://api:3000/livres?annee=lt.1900&select=id" | grep -o '"id"' | wc -lAffiché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.