Ce qui est généré automatiquement
UBC Data Bridge génère une référence technique HTML pour un point API à partir de ses paramètres enregistrés. Elle décrit l’adresse réelle, le format des données, les champs, les règles de validation, les paramètres, les réponses et les limites effectives. L’auteur du flux et l’intégrateur peuvent travailler à partir d’un même contrat lorsque le schéma ou le mode d’exécution évolue.
Pour la réception, les exemples reflètent le format du corps ou des fichiers, les données simulées, les champs obligatoires et les clés uniques. Pour la publication, ils reflètent les résultats enregistrés ou l’exécution à la demande, le format de réponse, les filtres et la pagination. La référence indique l’état du point : enregistrer un brouillon ne signifie pas que ses modifications sont déjà actives en Production.
1. Préparer le contrat du point de terminaison
- Nommez la connexion et le flux pour que le partenaire comprenne le jeu de données, par exemple « Stocks des magasins — test ».
- Complétez les paramètres d’adresse et de format. Pour la réception, saisissez un petit exemple valide, actualisez les champs et vérifiez les types, les indicateurs obligatoires et les clés.
- Pour la publication, reliez le résultat voulu, choisissez le mode d’exécution et décrivez les paramètres simplement. Confirmez lesquels sont obligatoires.
- Enregistrez les paramètres de la connexion et du bloc. Prévisualisez et simulez, corrigez les erreurs, puis publiez la version convenue du flux.
- Rouvrez la référence après les modifications. Comparez l’adresse, l’état Production et l’exemple de réponse à ce que le client doit utiliser.
2. Ouvrir la référence et accorder l’accès
Utilisez « Documentation technique » dans les propriétés du bloc API ou dans la connexion de publication enregistrée. « API → Documentation » liste les points accessibles. La route de référence d’un bloc est /api/flows/{flow}/blocks/{node}/api-docs; celle d’une connexion de publication, /api/connections/{connection}/api-docs; celle du catalogue, /api/api-docs. Ajoutez le préfixe de l’installation.
Ouvrir la référence nécessite un utilisateur connecté à Data Bridge. L’accès appartient à l’éditeur du flux ou à un utilisateur autorisé par son rôle à consulter « Documentation API » et capable de voir le flux. Une clé API seule n’ouvre pas la référence HTML. Rendre la publication des données publique ne rend pas la référence publique. Donnez à l’intégrateur les accès de compte nécessaires et transmettez la clé de requête séparément.
3. Configurer un client à partir des exemples
Commencez par « Démarrage rapide » : copiez l’adresse et configurez Postman ou curl. La référence contient des exemples Python et des explications d’authentification. Si les clients API concernés exigent HMAC, des instructions de signature apparaissent ; suivez les paramètres de votre propre clé. Les commandes « Copier » à côté des adresses et du code transfèrent les exemples sans ressaisie manuelle.
Insérez des valeurs de test et votre propre clé dans un environnement local sécurisé. La référence ne contient aucun secret de client. Pour JSON, conservez la structure et le chemin du tableau ; pour CSV, le séparateur et les en-têtes ; pour les fichiers, la méthode de transmission et le nom. Ne remplacez pas le format de requête par le format de saisie des données simulées : ces paramètres sont indépendants.
4. Vérifier la réussite et les refus attendus
Pour la réception, envoyez une petite requête valide, attendez la fin de la livraison et rapprochez le résultat de la destination. Testez ensuite un champ obligatoire manquant, un type invalide, un doublon de clé unique et la répétition d’une livraison avec le même Idempotency-Key. Le refus doit être compréhensible pour le client et la répétition ne doit pas créer d’exécution supplémentaire.
Pour la publication, testez la première page et la suivante, un filtre obligatoire, une sélection vide et des données anciennes. En mode exécution, suivez next avec le run.id figé jusqu’à la fin. Testez séparément une clé invalide, un flux interdit et la limite de fréquence. Consignez l’état HTTP, le code d’erreur, la livraison ou l’exécution et le nombre de lignes attendu.
5. Maintenir le contrat en exploitation
Rapprochez une requête échouée avec « Paramètres → API → Audit des requêtes » ou « Requêtes API » dans le menu du bloc. Vérifiez la méthode, la direction, l’état, la durée et la réponse. L’enregistrement des corps dépend de l’audit : ils peuvent contenir des données métier ; choisissez donc le périmètre et la durée de conservation nécessaires.
La table des limites de la référence présente les valeurs effectives : taille de requête, file, attente, taille de page et autres paramètres du point concerné. Rouvrez-la après modification des limites. Les données d’entrée d’une livraison sont nettoyées après sa fin ; historique et audit ont leurs propres règles de conservation. Si le contrat d’un partenaire change, utilisez une nouvelle version d’adresse et convenez de la migration en conservant l’ancienne pendant la transition.