Blog / Article #82

Idempotence : le mot qui fait vibrer les devs (et les APIs)

Ah, l’idempotence. Ce mot qui sonne comme une maladie rare ou un sortilège de Harry Potter, mais qui, en réalité, est juste un concept technique que tout le monde cite sans toujours bien le comprendre. Pourtant, dès qu’on parle d’APIs, de requêtes HTTP ou de résilience des systèmes, il finit par pointer son nez, comme un invité un peu trop collant à une soirée. Alors, c’est quoi cette fameuse idempotence que le vibecoding (et les lead devs un peu trop enthousiastes) brandissent comme une panacée ? Ce n’est ni magique ni révolutionnaire, mais c’est sacrément utile.

L’idempotence, ou l’art de ne pas tout casser (deux fois)

En termes simples, une opération est idempotente si l’exécuter plusieurs fois de suite donne le même résultat que l’exécuter une seule fois. Imaginez un bouton « Like » sur un réseau social : cliquer une fois like le post, cliquer deux fois ne devrait pas liker le post deux fois (sauf si vous êtes un bot russe, mais c’est une autre histoire). En HTTP, ça se traduit par des méthodes comme GET, PUT ou DELETE, qui sont conçues pour être idempotentes, contrairement à POST, qui ne l’est généralement pas.

Pourquoi c’est important ? Parce que le web est un endroit chaotique. Les requêtes peuvent être dupliquées, les réseaux peuvent lâcher, et les utilisateurs peuvent appuyer 15 fois sur « Envoyer » par impatience. Si votre API n’est pas idempotente, vous risquez de vous retrouver avec des commandes en double, des paiements répétés, ou pire : des données corrompues. Bref, un cauchemar pour les ops et un terrain de jeu pour les bugs.

Les méthodes HTTP et leur petit caractère idempotent

Revenons aux bases. En HTTP, certaines méthodes sont censées être idempotentes, mais ce n’est pas toujours le cas dans la vraie vie. Voici le tableau d’honneur (et de déshonneur) :

• GET : Idempotente. Récupérer une ressource ne la modifie pas (en théorie). Si vous appelez GET /users/123 100 fois, vous obtiendrez toujours les mêmes données (sauf si quelqu’un d’autre les modifie entre-temps, mais là, c’est une autre problématique).
• PUT : Idempotente. Remplacer une ressource par une autre version donne le même résultat, peu importe le nombre de fois où vous le faites. PUT /users/123 avec les mêmes données deux fois ? Pas de souci.
• DELETE : Idempotente. Supprimer une ressource une fois ou dix fois ne change rien : elle reste supprimée (ou retourne une erreur 404, ce qui est aussi un état stable).
• POST : Non idempotente. C’est la méthode par défaut pour créer des ressources, et c’est là que les ennuis commencent. Envoyer deux fois POST /orders peut créer deux commandes identiques, et là, bonjour les dégâts.

Le problème, c’est que beaucoup de devs utilisent POST pour tout, par habitude ou par paresse. Résultat : des APIs qui se comportent comme des adolescents en crise, avec des effets de bord imprévisibles. Si vous voulez une API robuste, respectez les bonnes pratiques : POST pour créer, PUT pour remplacer, PATCH pour modifier partiellement (même si PATCH est un peu le vilain petit canard de l’idempotence).

Comment rendre son API idempotente (sans se prendre la tête)

Bon, maintenant que vous savez ce qu’est l’idempotence, comment l’appliquer sans transformer votre code en usine à gaz ? Voici quelques pistes, sans tomber dans le dogmatisme :

D’abord, utilisez les bonnes méthodes HTTP. Si vous faites un POST pour une opération qui devrait être idempotente, vous êtes déjà dans le faux. Ensuite, ajoutez des clés d’idempotence pour les opérations critiques. Par exemple, si vous devez gérer des paiements, envoyez un Idempotency-Key dans les headers. Le serveur peut alors vérifier si la requête a déjà été traitée et éviter les doublons.

Voici un exemple simple en Node.js avec Express :

const express = require('express');
const app = express();
app.use(express.json());

const processedRequests = new Set();

app.post('/charge', (req, res) => {
    const idempotencyKey = req.headers['idempotency-key'];
    
    if (processedRequests.has(idempotencyKey)) {
        return res.status(409).json({ error: 'Request already processed' });
    }
    
    processedRequests.add(idempotencyKey);
    // Traiter la requête ici...
    res.json({ success: true });
});

app.listen(3000, () => {
    console.log('Server running on port 3000');
});

Bien sûr, dans un vrai projet, vous ne stockerez pas les clés en mémoire (sauf si vous aimez les crashes), mais l’idée est là : vérifiez avant de traiter.

Autre astuce : concevez vos endpoints pour qu’ils soient naturellement idempotents. Par exemple, au lieu d’avoir un endpoint POST /increment-counter (qui n’est clairement pas idempotent), utilisez PUT /counter avec la nouvelle valeur. Simple, efficace, et sans surprise.

L’idempotence, ce n’est pas une religion

Attention, je ne suis pas en train de dire que l’idempotence doit régir toute votre vie de dev. Parfois, c’est juste du overengineering inutile. Si vous gérez un blog perso avec trois utilisateurs, vous n’avez probablement pas besoin de clés d’idempotence pour les commentaires. En revanche, si vous travaillez sur un système de paiement ou une API critique, c’est une bonne pratique à ne pas négliger.

Le vrai piège, c’est de croire que l’idempotence résout tous les problèmes. Non, elle ne vous protégera pas des bugs dans votre logique métier, ni des requêtes mal formées, ni des utilisateurs qui cliquent comme des fous sur « Rafraîchir ». Mais elle peut éviter des catastrophes évitables, et ça, c’est déjà pas mal.

Alors, la prochaine fois que quelqu’un vous parlera d’idempotence comme si c’était la huitième merveille du monde, souriez, hochez la tête, et vérifiez quand même que votre POST n’est pas en train de créer des doublons. Parce que dans le doute, mieux vaut prévenir que guérir.

Et surtout, rappelez-vous : une API idempotente, c’est comme un bon café. Ça ne résout pas tous vos problèmes, mais au moins, ça évite les mauvaises surprises.