Une API, interface de programmation d'application, n'est qu'une manière documentée pour un logiciel de demander des données à un autre logiciel, ou de déclencher une action. Quand un CRM envoie un nouveau contact à une plateforme d'emailing, ou qu'une boutique en ligne transmet une commande à un système comptable, ils utilisent des API.
Trois schémas courants
Requête / réponse
Un système demande, l'autre répond : "donne-moi ce client", "crée cette commande". Simple et prévisible, mais nécessite qu'un côté sache quand demander.
Webhooks
Au lieu de demander de façon répétée, le système source pousse un événement vers une URL quand quelque chose se produit : "une nouvelle facture a été créée", "un paiement a réussi". Latence plus faible et plus efficace pour les flux pilotés par les événements.
Synchronisation planifiée
Des tâches périodiques déplacent les données par lots, chaque heure, chaque nuit, chaque semaine. Utile quand la fraîcheur n'est pas critique et qu'un push est peu pratique.
La plupart des intégrations réelles combinent au moins deux de ces approches.
Ce qui rend une intégration fiable
- Propriété claire des données. Un système est la source de vérité pour chaque donnée. Les autres reçoivent des copies.
- Opérations idempotentes. Rejouer deux fois le même appel produit le même résultat, essentiel pour les webhooks et les réseaux instables.
- Une gestion des erreurs visible. Les échecs aboutissent quelque part où un humain peut les voir, pas dans un journal silencieux que personne ne lit.
- Limites de débit respectées. Les bonnes intégrations ralentissent quand l'autre côté est lent ou bridé.
- Conscience du versionnage. Les API changent. Traitez l'intégration comme du code qui a besoin de mises à jour, pas comme un câblage ponctuel.
Ce qui rend une intégration fragile
- Des exports CSV envoyés par e-mail dans toute l'entreprise et réimportés manuellement.
- Des identifiants codés en dur dans des endroits que personne ne se rappelle.
- Un long script unique qui fait tout sans logique de réessai.
- Des échecs silencieux, les données cessent de circuler, et personne ne le remarque pendant des semaines.
- Une synchronisation bidirectionnelle sans règles de conflit claires : qui gagne quand les deux côtés ont changé ?
Middleware ou intégration directe ?
Il existe trois approches principales :
- Intégration directe : le système A parle directement au système B. Le plus simple pour un seul lien, devient brouillon quand il y en a beaucoup.
- Plateforme d'intégration (iPaaS) : un outil dédié comme une plateforme de workflow gère les connecteurs. Bon pour les flux simples et courants ; peut être coûteux et opaque pour une logique complexe.
- Middleware sur mesure : un petit service interne qui porte la logique d'intégration, les traductions et la gestion des erreurs. Souvent le bon choix quand la logique est spécifique à l'entreprise.
La meilleure réponse dépend du nombre de systèmes qui doivent se parler, de la quantité de logique sur mesure impliquée, et de votre préférence à placer les règles métier dans l'interface d'un fournisseur ou dans du code que vous possédez.
Un exemple concret de webhook
Supposons qu'une plateforme e-commerce doive notifier votre système comptable chaque fois qu'une commande est payée. Au lieu d'interroger chaque minute, la boutique appelle votre point de terminaison avec une petite charge utile JSON :
{
"event": "order.paid",
"event_id": "evt_8f3c21a9",
"occurred_at": "2024-11-12T09:41:07Z",
"order": {
"id": "ORD-10427",
"total": 1499.00,
"currency": "PLN",
"customer_email": "k.nowak@example.com"
}
}Le service récepteur doit accepter la requête, vérifier un en-tête de signature, stocker l'event_id, et renvoyer rapidement un 200. Le travail réel, comme la création d'une facture, se fait dans une tâche en arrière-plan. Si le même événement arrive deux fois, l'event_id stocké empêche une facture en double.
Règle générale : les gestionnaires de webhooks doivent accuser réception rapidement et effectuer le travail de façon asynchrone. Tout ce qui est lent ou fragile, un appel à une API tierce, un rendu PDF, a sa place dans une file d'attente, pas dans le gestionnaire HTTP.
Gérer les réessais sans doublons
Toute intégration fiable a besoin d'une clé d'idempotence. Un schéma minimal en pseudo-code :
async function handleOrderPaid(event) {
if (await seen(event.event_id)) return; // already processed
await markSeen(event.event_id);
await queue.enqueue('create-invoice', event.order);
}Erreurs courantes
- Intégrer trop tôt. Si le processus n'est pas stable, l'intégration figera le désordre et le rendra plus difficile à changer.
- Synchronisation bidirectionnelle par défaut. Le sens unique est plus simple et souvent suffisant, ne passez au bidirectionnel que si l'entreprise en a vraiment besoin.
- Aucune surveillance. Une intégration sans alerte est un échec silencieux qui ne demande qu'à arriver.
- Couplage fort. Les changements d'un système ne devraient pas casser tous les autres. Conservez une couche de traduction.
Une approche réaliste
- Dessinez le flux de données : quel système possède quel champ, et qui a besoin de copies.
- Commencez par le flux unique le plus pénible et construisez-le d'abord en sens unique.
- Utilisez les webhooks là où la faible latence compte, la synchronisation planifiée là où elle ne compte pas.
- Ajoutez la surveillance dès le premier jour, pas après la première panne.
- Documentez les identifiants, les points de terminaison et la propriété, afin que l'intégration survive aux changements de personnel.
