Introduction

Toute API utile doit recevoir des données du client — un identifiant utilisateur dans l'URL, des options de filtrage dans la query string, ou un corps JSON contenant les données d'un formulaire. Avant de pouvoir construire des endpoints CRUD, vous devez savoir précisément où Express place chaque élément de données entrantes et comment le lire de manière fiable.

Cette leçon passe en revue les trois principales sources d'entrée — paramètres d'URL, query strings et corps de requête — puis met les trois à profit dans un ensemble complet d'endpoints CRUD pour une ressource simple.

Lecture des entrées : paramètres, query strings et corps

Express analyse les données de la requête entrante en trois objets distincts sur l'objet request.

Les paramètres d'URL sont des segments nommés du chemin. Vous les déclarez avec deux-points dans votre définition de route, et Express les rend disponibles sur `req.params`.

app.get('/users/:id', (req, res) => {
  const userId = req.params.id;
  res.json({ requested: userId });
});

Les query strings apparaissent après le point d'interrogation dans une URL, comme `/users?role=admin&limit=10`. Express les analyse automatiquement dans `req.query`.

app.get('/users', (req, res) => {
  const { role, limit } = req.query;
  res.json({ role, limit });
});

Le corps de la requête transporte des données structurées envoyées par le client, le plus souvent au format JSON. Express n'analyse pas le corps par défaut — vous devez enregistrer le middleware intégré `express.json()` avant vos routes.

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

app.use(express.json());

Une fois ce middleware en place, les payloads `POST` et `PUT` sont disponibles sur `req.body`.

Construire une API CRUD complète

Pour rester concentré sur la mécanique du routage, les exemples ci-dessous utilisent un tableau en mémoire comme magasin de données. Dans un vrai projet, vous remplaceriez les opérations sur le tableau par des appels à une base de données.

Commencez par les données et une fonction utilitaire pour générer des identifiants :

let users = [
  { id: 1, name: 'Alice', role: 'admin' },
  { id: 2, name: 'Bob',   role: 'user'  },
];
let nextId = 3;

Create — `POST /users` lit le corps et ajoute un nouvel enregistrement :

app.post('/users', (req, res) => {
  const { name, role } = req.body;

  if (!name || !role) {
    return res.status(400).json({ error: 'name and role are required' });
  }

  const newUser = { id: nextId++, name, role };
  users.push(newUser);
  res.status(201).json(newUser);
});

Read all — `GET /users` prend en charge le filtrage optionnel par rôle via la query string :

app.get('/users', (req, res) => {
  const { role } = req.query;
  const result = role ? users.filter(u => u.role === role) : users;
  res.json(result);
});

Read one — `GET /users/:id` utilise `req.params` pour trouver un seul enregistrement :

app.get('/users/:id', (req, res) => {
  const user = users.find(u => u.id === Number(req.params.id));
  if (!user) return res.status(404).json({ error: 'User not found' });
  res.json(user);
});

Update — `PUT /users/:id` combine les paramètres (quel enregistrement) avec le corps (nouvelles valeurs) :

app.put('/users/:id', (req, res) => {
  const index = users.findIndex(u => u.id === Number(req.params.id));
  if (index === -1) return res.status(404).json({ error: 'User not found' });

  const { name, role } = req.body;
  users[index] = { ...users[index], ...(name && { name }), ...(role && { role }) };
  res.json(users[index]);
});

Delete — `DELETE /users/:id` supprime l'enregistrement et renvoie `204 No Content` :

app.delete('/users/:id', (req, res) => {
  const index = users.findIndex(u => u.id === Number(req.params.id));
  if (index === -1) return res.status(404).json({ error: 'User not found' });

  users.splice(index, 1);
  res.status(204).send();
});

Erreurs courantes

Oublier `express.json()` est la source de confusion la plus fréquente pour les débutants. Si `req.body` est `undefined`, vérifiez que le middleware est bien enregistré et que le client envoie bien un en-tête `Content-Type: application/json`.

Ne pas convertir `req.params.id` en nombre avant de le comparer est un autre bug subtil. Les paramètres de route sont toujours des chaînes de caractères. Comparer la chaîne `"1"` au nombre `1` avec une égalité stricte renverra toujours `false`, donc vos appels à `find` ou `findIndex` manqueront silencieusement chaque enregistrement.

Renvoyer des données après avoir envoyé une réponse provoque un crash de type « headers already sent » dans Express. Utilisez toujours `return` avant les appels à `res` à l'intérieur des conditions, comme illustré dans les exemples ci-dessus.

Résumé

Express répartit les données de la requête entrante sur trois objets : `req.params` pour les segments d'URL, `req.query` pour les query strings, et `req.body` pour le payload JSON analysé. Enregistrer le middleware `express.json()` débloque l'analyse du corps. Une fois ces trois sources comprises, construire des endpoints CRUD standard revient à associer les méthodes HTTP et les codes de statut à la bonne opération sur les données — `POST` et `201` pour la création, `GET` pour les lectures, `PUT` pour les mises à jour, `DELETE` avec `204` pour la suppression.