Six modèles d’intégration pour relier de manière fiable les services Node.js

Envoyer une requête HTTP est simple ; maintenir une intégration fonctionnelle lorsque l’autre système est lent, indisponible ou de structure différente, voilà la véritable tâche. Ce guide présente six modèles qui se reproduisent fréquemment lorsque les services Node.js communiquent avec des fournisseurs de paiement, des CRM, des ERP ainsi qu’entre eux-mêmes, ainsi que les pièges qui distinguent une démonstration d’une intégration fiable.

1. Modèle demande-réponse : la base synchrone

Dans ce modèle, le client envoie une requête, le serveur effectue le travail et la réponse revient par la même connexion. Il couvre la plupart des opérations courantes : connexion, création ou mise à jour de fiches, récupération d’un client, suppression d’une ressource.

app.get("/users/:id", async (req, res) => {
  const user = await db.findUser(req.params.id);
  res.json(user);
});

C’est simple à déboguer et c’est la méthode par défaut pour les opérations CRUD. Sa faiblesse réside dans les tâches longues : un rapport volumineux ou un fichier de grande taille peut dépasser les délais d’attente du client ou du proxy. Notez également que ce gestionnaire renvoie null avec un statut 200 lorsque l’utilisateur n’existe pas ; une véritable extrémité réseau devrait répondre par 404.

2. Polling : demander des mises à jour jusqu’à ce que la tâche soit terminée

Lorsqu’un résultat ne peut pas être généré immédiatement, le serveur peut accepter la tâche, renvoyer un identifiant et permettre au client de vérifier à nouveau. Les cas typiques incluent l’attente du règlement d’un paiement, de la génération d’un rapport, du transcodage d’une vidéo ou de l’expédition d’une commande.

Démarrer une tâche renvoie son ID :

POST /reports

Response:
{
  "jobId": "abc123"
}

Le client vérifie ensuite périodiquement l’extrémité réseau de suivi d’état :

GET /reports/abc123/status

jusqu’à ce que la tâche indique qu’elle est terminée :

{
  "status": "completed"
}

Le polling est simple et compatible avec les pare-feu, c’est pourquoi de nombreux systèmes d’entreprise s’y fient encore. Son inconvénient réside dans le trafic inutile généré, car la plupart des vérifications renvoient « pas encore ». Éspacer les requêtes (en respectant le champ Retry-After si présent), fixer une date limite globale, et gérer à la fois les cas échoués et ceux terminés.

3. Webhooks : permettre à l’autre partie de vous appeler

Les webhooks inversent la direction. Au lieu que votre service fasse des demandes répétées, le fournisseur envoie une requête HTTP vers votre point de terminaison lorsque quelque chose se produit : un paiement réussit, une commande est passée, un message arrive, un client s’inscrit, les stocks changent. Stripe, Slack, GitHub et Shopify comptent fortement sur ce modèle.

Un récepteur minimal en Express :

app.post("/webhook/payment", (req, res) => {
  const event = req.body;

  if (event.type === "payment.success") {
    console.log("Payment received!");
  }

  res.sendStatus(200);
});

Cela montre la structure de base, mais un récepteur en environnement de production nécessite davantage :

• Vérifiez l’expéditeur. N’importe qui peut publier sur une URL publique. Les fournisseurs signent généralement chaque envoi, et vous devez vérifier cette signature (généralement par rapport au corps de la demande brute) avant de faire confiance à l’événement.
• Prévoyez des doublons. Les livraisons sont généralement réessayées jusqu’à ce qu’elles soient confirmées, de sorte que le même événement peut arriver plus d’une fois. Stockez les IDs des événements traités et assurez que les traitements soient idempotents.
• Confirmez rapidement. Retournez rapidement un code 2xx et reportez les tâches lentes dans une file d’attente ; sinon, le fournisseur pourrait expirer et réenvoyer le message.

L’intégration basée sur les événements est de plus en plus privilégiée car elle élimine le trafic de sondage.

4. Authentification : prouver qui appelle

Toute intégration commence par des identifiants. Trois approches couvrent la plupart des cas.

Clés API

Le schéma le plus simple envoie un secret partagé dans une en-tête :

GET /users

x-api-key: abc123xyz

Avec Node.js et axios, la clé doit provenir de la configuration, jamais du code source :

axios.get(url, {
  headers: {
    "x-api-key": process.env.API_KEY
  }
});

Les clés API conviennent aux outils internes et aux intégrations simples serveur-à-server. Elles ne comportent ni date d’expiration ni identité utilisateur en soi ; il convient donc de les renouveler et de limiter leur portée autant que le fournisseur le permet.

JWT

Les JWT permettent une authentification sans état. La séquence habituelle est la suivante :

1. L’utilisateur se connecte.
2. Le serveur émet un jeton signé.
3. Le client conserve ce jeton.
4. Chaque requête ultérieure le transmet dans un en-tête :

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Émission d’un JWT en Node.js :

const token = jwt.sign(
  { userId: 1 },
  process.env.JWT_SECRET
);

Tout service disposant de la clé de vérification peut valider le jeton sans stockage de session, ce qui convient aux microservices. Le problème réside dans la révocation : un jeton reste valide jusqu’à son expiration, il est donc toujours nécessaire de définir expiresIn, ce que cet extrait omet.

OAuth 2.0

OAuth 2.0 est ce qui permet le accès délégué : « Se connecter avec Google », la connexion Facebook, l’authentification unique d’entreprise Microsoft, les connecteurs CRM et tout application tierce agissant au nom d’un utilisateur. Dans le flux de code d’autorisation courant :

1. L’utilisateur approuve l’accès demandé auprès du fournisseur.
2. Le fournisseur redirige vers votre site avec un code d’autorisation à courte durée de vie.
3. Votre serveur échange ce code contre un jeton d’accès.
4. Les appels API sont effectués à l’aide de ce jeton d’accès.

Vale la peine d’être étudié en profondeur : les tokens d’accès et de renouvellement, le flux du code d’autorisation, le flux des identifiants du client pour les appels machine à machine, PKCE et OpenID Connect, une couche d’identité par-dessus OAuth.

5. Résilience : conception pour les pannes

Les réseaux tombent en temps limité et les dépendances cessent de fonctionner. Les intégrations fiables partent du principe que cela peut arriver.

Réessayer les appels échoués

Un cycle de réessai de base :

for (let i = 0; i < 3; i++) {
  try {
    return await axios.get(url);
  } catch (error) {
    console.log("Retrying...");
  }
}

Au stade actuel, il réessaie immédiatement sans pause, et si les trois tentatives échouent, il renvoie undefined au lieu de lancer la dernière erreur, ce qui empêche l’appelant de savoir ce qui a mal tourné. Il faut relancer l’erreur après la dernière tentative, et ne réessayer que les pannes temporaires (erreurs de réseau, temps limités, codes 5xx, 429), pas les erreurs 4xx qui échoueront de la même manière à chaque fois. Faites attention à réessayer des requêtes non idempotentes comme les paiements, sauf si l’API prend en charge des clés d’idempotence.

Délais d’expiration

axios.get(url, {
  timeout: 5000
});

Retard exponentiel

Essayer à intervalles fixes continue de solliciter un service en difficulté :

1s
1s
1s
1s

Doublement du temps d’attente à chaque tentative lui donne plus de temps pour se remettre :

1s
2s
4s
8s
16s

Le calcul s’effectue en une seule ligne :

const delay = attempt =>
  Math.pow(2, attempt) * 1000;

Fixez un plafond au délai maximal et ajoutez des variations aléatoires afin que de nombreux clients en panne en même temps ne tentent pas leurs requêtes de manière synchronisée.

Déflecteurs de circuit

6. Transformation des données : conversion entre systèmes

Deux systèmes coïncident rarement en ce qui concerne la structure des données, donc une grande partie du travail d’intégration consiste en des conversions.

Mappage des champs

{
  "firstName": "John"
}

un autre attend snake_case :

{
  "first_name": "John"
}

function transform(user) {
  return {
    first_name: user.firstName
  };
}

Les fonctions de mappage pures sont faciles à tester unitairement et permettent d’éviter que les particularités des fournisseurs n’affectent la logique métier.

JSON et XML

De nombreux systèmes anciens utilisent encore XML tandis que les services plus récents génèrent du JSON, donc une couche d’intégration convertit souvent entre les deux dans les deux sens.

Dates

Une partie peut envoyer des dates au format ISO :

2026-06-26

alors que l’autre attend une notation où le jour précède la date :

26/06/2026

Effectuez des conversions explicites et soyez clair concernant les fuseaux horaires lorsque les valeurs incluent des heures ; une date décalée après minuit est un bug classique d’intégration.

Montants monétaires

Un service indique un montant décimal :

{
  "amount": 10.50
}

l’autre exige des unités secondaires entières :

{
  "amount_cents": 1050
}

Les valeurs en virgule flottante ne peuvent pas représenter avec précision tous les décimaux ; il convient donc d’arrondir lors de la conversion (par exemple Math.round(amount * 100)) et d’utiliser des centimes entiers en interne.

Comment ces modèles se combinent dans la pratique

Une architecture d’entreprise typique place un gateway Node.js devant plusieurs backends :

Frontend
   |
Node.js API Gateway
   |
   +-- Authentication Service
   +-- Payment Service
   +-- CRM Service
   +-- ERP Systems
   +-- Notification Service

Ces connexions combinent les modèles mentionnés ci-dessus : API demande-réponse, JWT et OAuth, webhooks, mécanismes de tentative répétée et de protection contre les pannes, couches de transformation, ainsi que des outils de surveillance et d’audit. Pour les ingénieurs qui s’orientent vers le travail d’intégration, les domaines qui rapportent rapidement des résultats sont les API REST, les webhooks, JWT, OAuth 2.0, la transformation des données et la conception orientée événements, suivis par les techniques de tentative répétée et de résilience, puis par le polling et les circuit breakers.

Points clés

• Utilisez le modèle demande-réponse pour les opérations rapides ; passez à la surveillance ou aux webhooks lorsque le traitement prend du temps.
• Vérifiez les signatures des webhooks, éliminez les doublons d’événements et confirmez rapidement leur réception.
• Gardez les identifiants dans la configuration, fixez une date d’expiration pour les tokens et maîtrisez correctement les flux OAuth.
• Réessayez uniquement en cas d’échecs temporaires, avec des délais de timeout, un recul exponentiel limité et du jitter.
• Isolez la mise en correspondance des données dans des fonctions pures testées, et traitez les dates ainsi que l’argent avec une extrême prudence.