Aller au contenu

Ressources/Connecteurs

Connecteurs

Écrire un connecteur sur mesure avec le SDK.

Pagination, curseur, schéma et certification : les étapes pour relier une API à votre modèle, à partir du connecteur de démonstration demo-crm.

L'équipe Impulse Lab · 5 min de lecture

Exemple de démonstration : demo-crm utilise une API simulée et six messages. Ce n'est pas une promesse de délai pour intégrer un CRM réel.

Définir la ressource avant de coder

Commencez par une ressource précise : des messages, des factures ou des contacts. Identifiez son identifiant stable, son champ de modification et la manière dont la source signale une suppression. Une API qui renvoie une liste ne garantit pas que cette liste représente tout le périmètre.

Le connecteur demo-crm déclare une ressource de messages avec un schéma. Le modèle exploite ensuite le numéro SAV pour relier chaque message à son dossier. Le connecteur transporte les données ; le mapping porte cette relation métier.

Paginer et reprendre sans perdre de données

Une synchronisation doit pouvoir reprendre après une panne. Dans la démonstration, les messages arrivent par pages de deux et le curseur permet de continuer la lecture. Le journal du run indique où le traitement s'est arrêté.

Sur une vraie API, vérifiez la durée de validité du curseur, l'ordre des résultats et les limites de requêtes. Un identifiant stable permet de reconnaître une observation déjà reçue. Il faut aussi décider comment traiter une modification pendant la pagination.

Testez un échec sur une page intermédiaire. Une reprise réussie doit récupérer la suite sans ignorer une ligne et sans rejouer des effets externes. Un simple test de la première page ne prouve pas cette propriété.

Valider et certifier le connecteur

Le schéma déclare les champs, leurs types et leur caractère obligatoire. Une valeur qui ne respecte pas ce schéma doit être isolée et expliquée, sans empêcher l'application des lignes valides.

La fixture de certification fournit un jeu d'entrées reproductible. Les capacités annoncées et les ressources couvertes sont vérifiées avant l'usage du connecteur. Si le connecteur déclare des lectures get ou list, ces lectures font aussi partie de la certification.

Les credentials restent hors des fixtures et des manifestes publics. La configuration de connexion ne doit jamais publier un token dans un exemple ou un message d'erreur.

Vérifier le premier run dans la console

Après la certification, lancez une synchronisation sur un périmètre limité. Vérifiez les nombres de lignes capturées, appliquées et mises en quarantaine, puis ouvrez un objet pour retrouver sa provenance.

Une donnée capturée sans mapping actif ne devient pas un objet métier par magie. Il faut déclarer et publier le mapping correspondant. Le journal permet de distinguer une erreur de transport, une entrée invalide et une relation métier impossible à résoudre.

Le résultat attendu est concret : vous pouvez expliquer comment une ligne source a produit une valeur et comment reprendre après un échec. C'est un meilleur critère de livraison qu'un délai annoncé sans connaître l'API.

Pour aller plus loin

Toutes les ressources

Quelle source fait foi chez vous ?
On le regarde ensemble en 30 minutes.