L’interconnexion d’API en détail : de la source à la destination

Relier deux logiciels par leurs API paraît simple : récupérer une donnée ici, l’envoyer là. En pratique, un flux fiable comporte une série d’étapes et de cas particuliers. Voici le détail, de la source à la destination.

1. Le déclencheur

Qu’est-ce qui lance le flux ? Deux approches :

• L’interrogation périodique (« polling ») : on demande régulièrement à la source s’il y a du nouveau. Simple, mais avec un décalage et des appels inutiles ;
• Le webhook : la source prévient elle-même, par un appel HTTP, dès qu’un événement se produit. Plus réactif, mais il faut une adresse capable de recevoir l’appel et de vérifier son authenticité.

2. L’authentification

Chaque API exige de prouver qui l’appelle : clé d’accès, jeton porté dans l’en-tête de la requête, ou protocole OAuth 2.0 avec autorisation de l’utilisateur et jetons à renouveler. Ces secrets doivent être stockés à l’abri et limités aux droits nécessaires.

3. La requête

Une API web (le plus souvent de style REST) se manipule avec des méthodes HTTP : lire (GET), créer (POST), modifier (PUT ou PATCH), supprimer (DELETE). Les données s’échangent en général au format JSON.

4. La transformation

Entre la source et la destination, les données sont adaptées : correspondance des champs (mapping), conversion des types, des dates et des devises, regroupement ou découpage de valeurs, ajout de valeurs fixes. C’est l’étape qui demande le plus de réflexion métier. Voir le rôle d’un middleware.

5. L’envoi et la lecture de la réponse

La réponse de l’API se lit d’abord par son code : les codes en 2xx indiquent un succès, ceux en 4xx une erreur côté demandeur (401 : non authentifié, 403 : non autorisé, 404 : introuvable, 429 : trop de requêtes), ceux en 5xx un problème côté serveur. Chaque cas appelle une réaction différente.

6. Les volumes : pagination et limites de débit

• Pagination : une API renvoie les résultats par pages ; il faut les parcourir toutes ;
• Limites de débit : le nombre d’appels est plafonné ; au-delà, l’API répond 429 et il faut patienter ;
• Traitement par lots : pour de gros volumes, mieux vaut regrouper les envois.

7. Les doublons et l’idempotence

Un flux interrompu puis relancé peut envoyer deux fois la même donnée. Pour l’éviter, on s’appuie sur un identifiant commun reconnu des deux côtés, ou sur une clé d’idempotence : renvoyer la même requête produit alors le même résultat, sans créer de doublon.

8. Les erreurs et les reprises

• réessayer automatiquement, avec une attente de plus en plus longue entre les essais ;
• distinguer les erreurs passagères (réseau, 5xx) des erreurs définitives (donnée invalide) ;
• mettre de côté les échanges en échec pour les rejouer plus tard ;
• alerter quand un échange reste bloqué.

9. La sécurité et la protection des données

• communications chiffrées (HTTPS) ;
• droits minimum pour chaque clé d’accès ;
• journaux qui évitent de stocker des données sensibles ;
• réflexion sur la conservation : ce qui n’est pas gardé ne peut pas fuir. C’est le choix retenu pour La Passerelle, l’un de mes projets personnels, qui ne conserve pas les données qui transitent.

10. La supervision

Un flux qui s’arrête sans que personne ne le sache est pire qu’un flux absent. Il faut surveiller l’exécution, les erreurs et la disponibilité des systèmes reliés (supervision).

Une liste de contrôle avant de lancer un flux

1. le déclencheur est choisi (polling ou webhook) ;
2. les accès sont créés avec des droits limités et stockés à l’abri ;
3. le mapping des champs est documenté ;
4. les cas d’erreur, de doublon et de dépassement de limite sont prévus ;
5. une alerte existe en cas d’échec ;
6. les données personnelles concernées sont identifiées.

Pour les bases, voir relier ses logiciels par API : par où commencer.