Créer une API RESTful avec ExpressJS - Guide Étape par Étape pour Débutants

Introduction : Qu’est-ce qu’une API RESTful et Pourquoi l’Utiliser ?

Une API RESTful est comme un serveur qui répond à des demandes simples pour manipuler des données (par exemple, une liste de tâches). "REST" signifie qu’on utilise des commandes standard comme GET (lire), POST (ajouter), PUT (modifier), et DELETE (supprimer). Avec ExpressJS, c’est facile à faire, et ça peut être utilisé par des applications web ou mobiles. Nous allons créer une API pour gérer des tâches, comme "Faire les courses".

Étape 1 : Préparer Votre Environnement

Avant de coder, préparons tout ce qu’il faut. Si vous avez suivi les tutoriels précédents, vous avez déjà Node.js et ExpressJS. Voici les étapes :

• Vérifiez Node.js : Ouvrez un terminal et tapez node -v. Si une version apparaît (ex. : v16.13.0), c’est bon. Sinon, téléchargez Node.js sur nodejs.org.
• Créez un dossier projet : Faites un dossier nommé par exemple : "api-restful-express" sur votre ordinateur.
• Initialisez le projet : Dans le terminal, allez dans ce dossier avec cd chemin/vers/api-restful-express , puis tapez npm init -y. Cela crée un fichier package.json.
• Installez ExpressJS : Tapez npm install express. Express est tout ce dont nous avons besoin pour cet exemple simple.

Étape 2 : Créer une API RESTful Simple

Commençons par une API qui gère une liste de tâches stockée en mémoire (pas dans une base de données pour simplifier).

Exemple de Code : API RESTful pour les Tâches

Créez un fichier nommé index.js dans votre dossier "api-restful-express" et ajoutez ce code. Il permet de lire, ajouter, modifier, et supprimer des tâches.

📋 Copier le code

var express = require('express');
var app = express();

// Liste temporaire pour stocker les tâches
var taches = [
    { id: 1, titre: "Faire les courses" },
    { id: 2, titre: "Apprendre ExpressJS" }
];

// Activer la lecture des données JSON et formulaires
app.use(express.json());
app.use(express.urlencoded({ extended: false }));

// GET : Lire toutes les tâches
app.get('/taches', function(req, res) {
    res.json(taches);
});

// GET : Lire une tâche spécifique par ID
app.get('/taches/:id', function(req, res) {
    var tache = taches.find(t => t.id === parseInt(req.params.id));
    if (tache) {
        res.json(tache);
    } else {
        res.status(404).json({ message: "Tâche non trouvée" });
    }
});

// POST : Ajouter une nouvelle tâche
app.post('/taches', function(req, res) {
    var nouvelleTache = {
        id: taches.length + 1,
        titre: req.body.titre
    };
    taches.push(nouvelleTache);
    res.status(201).json(nouvelleTache);
});

// PUT : Modifier une tâche existante
app.put('/taches/:id', function(req, res) {
    var tache = taches.find(t => t.id === parseInt(req.params.id));
    if (tache) {
        tache.titre = req.body.titre;
        res.json(tache);
    } else {
        res.status(404).json({ message: "Tâche non trouvée" });
    }
});

// DELETE : Supprimer une tâche
app.delete('/taches/:id', function(req, res) {
    var index = taches.findIndex(t => t.id === parseInt(req.params.id));
    if (index !== -1) {
        taches.splice(index, 1);
        res.status(204).send();
    } else {
        res.status(404).json({ message: "Tâche non trouvée" });
    }
});

app.listen(3000, function() {
    console.log("Serveur démarré sur http://localhost:3000/taches");
});
    

Explication Détaillée du Code

Voici chaque ligne expliquée très simplement pour les débutants :

• var express = require('express'); : On importe ExpressJS pour créer notre serveur.
• var taches = [...] : On crée une liste de tâches avec des objets (chaque tâche a un id et un titre). C’est comme une mini-base de données temporaire.
• app.use(express.json()); : On active un outil pour lire les données envoyées au format JSON (un format simple pour échanger des données).
• app.use(express.urlencoded({ extended: false })); : On active la lecture des données des formulaires (optionnel ici, mais utile).
• app.get('/taches', ...); : Cette route renvoie toutes les tâches en JSON quand on visite "/taches". res.json envoie les données dans un format que les applications comprennent.
• app.get('/taches/:id', ...); : Cette route renvoie une tâche spécifique par son ID (ex. : "/taches/1").
  • taches.find(...) : On cherche la tâche avec l’ID donné. parseInt transforme le texte de l’URL en nombre.
  • res.status(404) : Si la tâche n’existe pas, on envoie une erreur 404 ("non trouvé").
• app.post('/taches', ...); : Cette route ajoute une nouvelle tâche.
  • { id: taches.length + 1, titre: req.body.titre } : On crée une tâche avec un nouvel ID et le titre envoyé.
  • taches.push(...) : On ajoute la tâche à la liste.
  • res.status(201) : "201" signifie "créé avec succès".
• app.put('/taches/:id', ...); : Cette route modifie une tâche.
  • tache.titre = req.body.titre; : On remplace le titre par celui envoyé.
• app.delete('/taches/:id', ...); : Cette route supprime une tâche.
  • taches.findIndex(...) : On trouve la position de la tâche dans la liste.
  • taches.splice(index, 1); : On supprime la tâche à cette position.
  • res.status(204) : "204" signifie "supprimé avec succès" (pas de contenu à renvoyer).
• app.listen(3000, ...); : On démarre le serveur.

Étape 3 : Tester l’API

Pour tester cette API, vous pouvez utiliser un outil comme Postman ou votre terminal avec curl. Voici comment :

• Démarrez le serveur : Sauvegardez index.js, tapez node index.js dans le terminal.
• Lire toutes les tâches : Ouvrez un navigateur ou tapez curl http://localhost:3000/taches. Vous verrez la liste initiale.
• Lire une tâche : Tapez curl http://localhost:3000/taches/1. Vous verrez la tâche avec l’ID 1.
• Ajouter une tâche : Tapez curl -X POST -H "Content-Type: application/json" -d '{"titre":"Nettoyer"}' http://localhost:3000/taches. Une nouvelle tâche est ajoutée.
• Modifier une tâche : Tapez curl -X PUT -H "Content-Type: application/json" -d '{"titre":"Nettoyer la maison"}' http://localhost:3000/taches/3. La tâche est mise à jour.
• Supprimer une tâche : Tapez curl -X DELETE http://localhost:3000/taches/2. La tâche est supprimée.

Pour tester dans un navigateur : Visitez http://localhost:3000/taches pour voir la liste. Pour les autres actions (POST, PUT, DELETE), utilisez Postman ou curl, car le navigateur seul ne peut pas les faire facilement.

Étape 4 : Comprendre les Commandes curl pour Tester l’API

Dans l’étape précédente, nous avons utilisé des commandes comme curl http://localhost:3000/taches ou curl -X POST -H "Content-Type: application/json" -d '{"titre":"Nettoyer"}' http://localhost:3000/taches pour tester notre API. Mais à quoi servent ces mots et symboles ? Dans cette section, nous allons tout expliquer simplement, étape par étape, pour que même un débutant complet comprenne comment ça marche et pourquoi on les utilise.

Exemple de Commandes et Leur Explication

Voici les deux commandes que nous avons utilisées, suivies d’une explication détaillée de chaque partie :

Commande 1 : curl http://localhost:3000/taches

Cette commande simple demande à l’API de nous montrer toutes les tâches.

• curl : C’est un outil que vous tapez dans le terminal pour parler à un serveur (comme notre API). "curl" signifie "Client URL". Imaginez-le comme un messager qui va chercher des informations sur internet ou sur votre ordinateur (localhost).
• http://localhost:3000/taches : C’est l’adresse où le messager (curl) doit aller. Ici :
  • http:// : Le protocole, une règle pour communiquer avec le serveur.
  • localhost : Votre ordinateur (le serveur tourne chez vous).
  • :3000 : Le port où le serveur écoute (comme une porte spécifique).
  • /taches : La route de l’API qui renvoie la liste des tâches.

Ce que ça fait : Quand vous tapez cette commande, curl envoie une demande GET (lire) à l’API, et le serveur répond avec la liste des tâches en JSON, que vous verrez dans le terminal.

Commande 2 : curl -X POST -H "Content-Type: application/json" -d '{"titre":"Nettoyer"}' http://localhost:3000/taches

Cette commande plus longue ajoute une nouvelle tâche à l’API. Décomposons chaque partie :

• curl : Toujours notre messager qui va parler au serveur.
• -X POST : Le "-X" dit à curl quelle action faire, et "POST" signifie "ajouter quelque chose". Par défaut, curl utilise GET (lire), mais ici on veut créer une nouvelle tâche.
  • -X : Une option (un drapeau) qui change le type de demande.
  • POST : Une des commandes REST pour dire "envoie des données au serveur".
• -H "Content-Type: application/json" : Le "-H" ajoute une information sur ce qu’on envoie, et "Content-Type: application/json" dit au serveur qu’on envoie des données au format JSON.
  • -H : Signifie "Header" (en-tête), une note pour le serveur.
  • "Content-Type: application/json" : Indique que les données sont en JSON, un format simple comme {"clé": "valeur"}.
• -d '{"titre":"Nettoyer"}' : Le "-d" envoie les données qu’on veut ajouter, et {"titre":"Nettoyer"} est la nouvelle tâche.
  • -d : Signifie "data" (données), ce qu’on donne au serveur.
  • '{"titre":"Nettoyer"}' : Les données en JSON. "titre" est le nom du champ, "Nettoyer" est la valeur. Les guillemets simples (') entourent tout pour que le terminal comprenne.
• http://localhost:3000/taches : L’adresse où on envoie la nouvelle tâche (la même que pour lire, mais l’action POST change ce qui se passe).

Ce que ça fait : Cette commande dit à l’API : "Ajoute une tâche avec le titre ’Nettoyer’". Le serveur répond avec la nouvelle tâche créée, que vous verrez dans le terminal.

Pourquoi Utiliser curl ?

Votre navigateur (comme Chrome) peut faire des demandes GET facilement en visitant une URL comme http://localhost:3000/taches, et vous verrez la réponse dans la fenêtre du navigateur. Mais pour les actions comme POST (ajouter), PUT (modifier), ou DELETE (supprimer), le navigateur ne suffit pas, car il ne peut pas envoyer des données ou changer la méthode tout seul. C’est pourquoi on utilise curl dans le terminal : il envoie ces demandes directement au serveur, et la réponse s’affiche dans le terminal, pas dans le navigateur. Il n’y a pas de redirection vers le navigateur — tout se passe dans le terminal ! Curl est rapide et parfait pour tester une API sans interface graphique.

Comment Tester Ces Commandes

Pour essayer vous-même :

• Démarrez votre serveur : Assurez-vous que node index.js est lancé dans un terminal.
• Ouvrez un deuxième terminal : Laissez le serveur tourner dans le premier, et utilisez un autre pour taper les commandes.
• Tapez la commande simple : Entrez curl http://localhost:3000/taches et appuyez sur Entrée. Vous verrez la liste des tâches dans le terminal.
• Tapez la commande complexe : Entrez curl -X POST -H "Content-Type: application/json" -d '{"titre":"Nettoyer"}' http://localhost:3000/taches. Vous verrez la nouvelle tâche ajoutée dans le terminal.
• Vérifiez : Retapez curl http://localhost:3000/taches pour voir la liste mise à jour dans le terminal.

Si vous faites une erreur (ex. : oubli d’un guillemet), le terminal affichera un message. Relisez la commande et réessayez !

Étape 5 : Explorer d’Autres Commandes curl pour Tester Votre API

Dans l’étape précédente, nous avons utilisé des commandes simples comme curl http://localhost:3000/taches pour lire les tâches et curl -X POST -H "Content-Type: application/json" -d '{"titre":"Nettoyer"}' http://localhost:3000/taches pour en ajouter une. Mais saviez-vous que curl peut faire beaucoup plus ? Dans cette section, nous allons découvrir d’autres commandes et options utiles pour tester votre API RESTful. Tout sera expliqué simplement, comme si vous n’aviez jamais utilisé curl auparavant !

1. Tester les Autres Méthodes REST

Une API RESTful utilise quatre actions principales : GET (lire), POST (ajouter), PUT (modifier), et DELETE (supprimer). Nous avons vu GET et POST, voici comment faire PUT et DELETE avec curl :

Modifier une Tâche avec PUT

Commande : curl -X PUT -H "Content-Type: application/json" -d '{"titre":"Nettoyer la maison"}' http://localhost:3000/taches/1

• Ce que ça fait : Met à jour la tâche avec l’ID 1 pour changer son titre en "Nettoyer la maison".
• Détails :
  • -X PUT : Dit à curl d’utiliser PUT pour modifier une ressource.
  • -d '{"titre":"Nettoyer la maison"}' : Les nouvelles données à appliquer.

Supprimer une Tâche avec DELETE

Commande : curl -X DELETE http://localhost:3000/taches/2

• Ce que ça fait : Supprime la tâche avec l’ID 2.
• Détails :
  • -X DELETE : Dit à curl de supprimer la ressource.
  • Pas de -d ici, car on ne modifie rien, on supprime juste.

2. Options Utiles pour Plus de Contrôle

En plus des méthodes, curl a des options (des "drapeaux") qui changent son comportement. Voici quelques-unes qui peuvent vous aider :

Voir Plus de Détails avec -v

Commande : curl -v http://localhost:3000/taches

• Ce que ça fait : Affiche la liste des tâches, mais aussi des détails techniques (comme les en-têtes envoyés et reçus).
• Exemple de résultat : Vous verrez des lignes comme < HTTP/1.1 200 OK (le serveur dit "tout va bien").
• Pourquoi l’utiliser : Pour comprendre ce qui se passe entre curl et le serveur.

Afficher les En-têtes avec -i

Commande : curl -i http://localhost:3000/taches

• Ce que ça fait : Montre les en-têtes de la réponse (comme "Content-Type") avant la liste des tâches.
• Exemple de résultat : Content-Type: application/json suivi des données.
• Pourquoi l’utiliser : Pour vérifier comment le serveur formate sa réponse.

Sauvegarder la Réponse avec -o

Commande : curl -o taches.txt http://localhost:3000/taches

• Ce que ça fait : Enregistre la liste des tâches dans un fichier "taches.txt" au lieu de l’afficher dans le terminal.
• Pourquoi l’utiliser : Pour garder une trace de la réponse ou l’analyser plus tard.

Ajouter un En-tête Supplémentaire avec -H

Commande : curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer monjeton" -d '{"titre":"Nettoyer"}' http://localhost:3000/taches

• Ce que ça fait : Ajoute un en-tête "Authorization" (par exemple, pour une API sécurisée avec un jeton).
• Remarque : Notre API actuelle ne vérifie pas ça, mais c’est utile pour des projets futurs.

3. Combiner les Options

Vous pouvez mélanger ces options pour faire des tests plus avancés :

• Détails et sauvegarde : curl -v -o taches.txt http://localhost:3000/taches

  Affiche les détails dans le terminal et enregistre la réponse dans "taches.txt".

• Modifier avec détails : curl -v -X PUT -H "Content-Type: application/json" -d '{"titre":"Réviser Express"}' http://localhost:3000/taches/1

  Met à jour la tâche et montre les détails de la requête.

4. Où Trouver Toutes les Options ?

curl a des dizaines d’options ! Pour les découvrir :

• Tapez curl --help dans le terminal pour un résumé rapide.
• Tapez curl --manual pour un guide complet (attention, c’est très long !).

Comment Tester Ces Nouvelles Commandes

Pour essayer :

• Démarrez votre serveur : Assurez-vous que node index.js tourne.
• Ouvrez un terminal : Tapez une commande comme curl -X DELETE http://localhost:3000/taches/1 pour supprimer la tâche 1.
• Ajoutez des détails : Essayez curl -v http://localhost:3000/taches pour voir plus d’infos.
• Vérifiez : Relancez curl http://localhost:3000/taches pour voir les changements.

Ces commandes fonctionnent avec l’API que nous avons créée. Amusez-vous à les tester pour voir ce qu’elles font !

Conclusion

Félicitations ! Vous savez maintenant créer une API RESTful avec ExpressJS pour gérer des tâches. Vous avez appris à utiliser GET, POST, PUT, et DELETE pour lire, ajouter, modifier, et supprimer des données. Pour aller plus loin, explorez notre prochain tutoriel sur Scaffolding avec ExpressJS ou consultez la documentation ExpressJS.