Qu'est-ce que REST ?

REST (Representational State Transfer) est un style architectural, pas un protocole. Il définit un ensemble de contraintes sur la façon dont les services web doivent se comporter. Quand une API respecte ces contraintes, on la dit RESTful. L'idée clé est simple : un client envoie une requête à une URL qui représente une ressource, et le serveur répond avec une représentation de cette ressource — généralement du JSON.

Les six contraintes qui définissent REST sont : séparation client-serveur, absence d'état, mise en cache, interface uniforme, système en couches, et code à la demande (optionnelle). En pratique, celles qui comptent le plus au quotidien sont l'absence d'état et l'interface uniforme. L'absence d'état signifie que chaque requête doit contenir toutes les informations nécessaires à son traitement — le serveur ne conserve pas d'état de session entre les requêtes. L'interface uniforme signifie l'utilisation de méthodes HTTP standards et de patterns d'URL prévisibles.

Méthodes HTTP et leur signification

Les méthodes HTTP indiquent au serveur quelle action effectuer sur une ressource. Chaque méthode porte une signification sémantique précise qu'il faut respecter — l'ignorer conduit à des API confuses et difficiles à consommer.

GET récupère une ressource sans effets de bord. POST crée une nouvelle ressource. PUT remplace intégralement une ressource existante. PATCH met à jour partiellement une ressource. DELETE supprime une ressource.

Voici comment elles se rapportent à une ressource users typique :

GET    /users        → list all users
GET    /users/42     → get user with id 42
POST   /users        → create a new user
PUT    /users/42     → replace user 42 entirely
PATCH  /users/42     → update specific fields of user 42
DELETE /users/42     → delete user 42

GET et DELETE sont idempotents — les appeler plusieurs fois produit le même résultat. PUT est également idempotent. POST ne l'est pas — l'appeler deux fois crée généralement deux ressources.

Codes d'état HTTP

Les codes d'état indiquent au client ce qui s'est passé. Ils sont regroupés en cinq classes : 1xx information, 2xx succès, 3xx redirection, 4xx erreur client, 5xx erreur serveur. Ceux que vous utiliserez le plus souvent en développement d'API sont :

200 OK — la requête a réussi et il y a un corps de réponse. Utilisez ceci pour les réponses GET et PATCH réussies.

201 Created — une ressource a été créée avec succès. Utilisez ceci après un POST réussi. Incluez un en-tête Location pointant vers la nouvelle ressource.

204 No Content — succès, mais aucun corps à renvoyer. Utilisez ceci pour DELETE.

400 Bad Request — le client a envoyé des données invalides (champs manquants, types incorrects, échecs de validation).

401 Unauthorized — la requête ne contient pas de credentials d'authentification valides.

403 Forbidden — le client est authentifié mais n'a pas la permission.

404 Not Found — la ressource n'existe pas.

409 Conflict — la requête est en conflit avec l'état actuel (par exemple, créer un utilisateur avec un email qui existe déjà).

422 Unprocessable Entity — la requête est bien formée mais échoue à la validation sémantique.

500 Internal Server Error — une erreur s'est produite côté serveur. N'exposez jamais de stack trace ici en production.

Un exemple concret dans un handler Express :

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

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

  // imagine createUser() saves to a database and returns the new record
  const user = createUser({ email, name });

  res
    .status(201)
    .location(`/users/${user.id}`)
    .json(user);
});

En-têtes HTTP dans le contexte d'une API

Les en-têtes transportent des métadonnées sur la requête ou la réponse. Quelques-uns sont essentiels pour les API REST.

Content-Type déclare le format du corps de la requête ou de la réponse. Pour les API JSON, c'est toujours application/json. Express le définit automatiquement quand vous appelez res.json(), mais quand vous construisez des réponses brutes, vous devez le définir explicitement.

Accept indique au serveur quel format le client peut gérer. Les clients doivent envoyer Accept: application/json quand ils appellent une API JSON.

Authorization transporte les credentials. Le pattern le plus courant pour les API REST est l'authentification par token Bearer :

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Cache-Control pilote le comportement de cache pour les réponses GET. Pour des données publiques qui changent rarement, définir Cache-Control: public, max-age=300 réduit la charge sur votre serveur. Pour des données spécifiques à un utilisateur ou sensibles, utilisez Cache-Control: no-store.

Dans Express, vous pouvez lire les en-têtes entrants via req.headers et définir les sortants via res.set() :

app.get('/products', (req, res) => {
  const products = getProducts();
  res
    .set('Cache-Control', 'public, max-age=300')
    .json(products);
});

Résumé

REST est un style architectural basé sur une communication client-serveur sans état avec une interface uniforme. Les méthodes HTTP définissent l'action à effectuer sur une ressource — GET lit, POST crée, PUT remplace, PATCH met à jour, DELETE supprime. Les codes d'état communiquent le résultat avec précision : 2xx pour le succès, 4xx pour les erreurs client, 5xx pour les erreurs serveur. Les en-têtes transportent des métadonnées comme le type de contenu, les credentials d'authentification et les directives de cache. Maîtriser ces fondamentaux est ce qui distingue une API facile à intégrer d'une autre qui force les consommateurs à deviner.