Requête API
Interroge un logiciel tiers par son interface web pendant l'appel, range la réponse dans des variables, et prend la sortie Erreur dès que cela tarde ou échoue.
En bref
| Sorties | OK et Erreur |
| Champs | Méthode, Timeout, URL, Entêtes (1/ligne), Corps (POST/PUT), et un tableau d'extractions Variable et Chemin JSON |
| Méthodes | GET, POST, PUT, DELETE |
| Timeout proposé | 2, 3, 5, 8 ou 10 s, 5 s par défaut |
| Timeout réellement appliqué | 8 secondes au maximum, même si vous choisissez 10 |
| Attente d'établissement de la connexion | 2 secondes |
| Redirections suivies | 2 |
| Disjoncteur | 5 échecs consécutifs sur un même serveur ouvrent le circuit pendant 30 secondes |
Le texte d'aide affiché dans la fenêtre est : « Interroge une API HTTP et extrait des valeurs JSON dans des variables. Si l'API échoue ou dépasse le timeout, la sortie « Erreur » est prise. Utilise {{variable}} dans l'URL, les entêtes et le corps. »
Comment ça marche
Ce qu'est une API
Une API est la porte de service d'un logiciel : une adresse web qu'un autre programme interroge, et qui répond non pas une page à lire, mais une donnée structurée. La plupart répondent en JSON, un format qui range les informations par nom, à la façon d'un formulaire : {"client": {"nom": "Dupont", "statut": "premium"}}.
Le module envoie la requête, lit la réponse et en extrait ce qui vous intéresse.
Les variables dans la requête
L'URL, les Entêtes et le Corps acceptent des {{variables}}, remplacées juste avant l'envoi. C'est ainsi qu'on interroge le service sur l'appelant en cours : https://api.exemple.com/client/{{caller}}.
L'extraction
La réponse est rarement à prendre en bloc. Le tableau du bas associe un Chemin JSON à un nom de Variable. Le chemin se lit de l'extérieur vers l'intérieur, les niveaux séparés par des points : client.nom va chercher nom à l'intérieur de client. Une liste se parcourt par son rang, en commençant à zéro : 0.nom désigne le nom du premier élément.
Un chemin laissé vide rapporte la réponse entière : c'est ce qu'il faut quand le service répond directement un nombre ou un mot, sans structure autour.
Un chemin qui ne mène à rien donne une variable vide, sans erreur. La sortie OK est prise malgré tout, puisque le service a bien répondu.
Quand la sortie Erreur est prise
- l'URL est vide ;
- le service ne répond pas dans le délai ;
- il répond un code d'erreur, c'est-à-dire tout code hors de la famille des succès ;
- le disjoncteur est ouvert.
Le disjoncteur
Un service en panne ne doit pas ralentir tous vos appels. Après 5 échecs consécutifs vers un même serveur, le module cesse de l'appeler pendant 30 secondes : la sortie Erreur est prise immédiatement, sans attendre le délai et sans même envoyer la requête. Un premier succès remet le compteur à zéro.
C'est une protection, et cela explique une observation déroutante : pendant ces trente secondes, l'appel repart en Erreur en un clin d'œil, alors que le service est peut-être déjà rétabli.
Ce qu'il faut saisir
| Champ | Ce qui est attendu | Si vous le laissez vide |
|---|---|---|
| Méthode | GET pour lire, POST ou PUT pour envoyer, DELETE pour supprimer | GET |
| Timeout | le délai d'attente, ramené à 8 s au maximum à l'exécution | 5 s |
| URL | l'adresse complète, qui accepte des {{variables}} | la sortie Erreur est prise sans qu'aucun appel ne parte |
| Entêtes (1/ligne) | une entête par ligne, par exemple une clé d'authentification | aucune entête n'est envoyée |
| Corps (POST/PUT) | le contenu envoyé, en général du JSON | aucun contenu ; le corps est de toute façon ignoré en GET |
| Variable d'une extraction | le nom sous lequel ranger la valeur lue | la ligne est ignorée |
| Chemin JSON d'une extraction | le chemin vers la valeur, par exemple client.nom | la réponse entière est rangée dans la variable |
Le bouton Ajouter une extraction crée une ligne, Supprimer retire la sienne, Sauver ferme la fenêtre.
La marche à suivre
- Obtenez de votre prestataire l'adresse à interroger, la façon de s'authentifier, et un exemple de réponse. Sans exemple de réponse, vous ne pourrez pas écrire les chemins d'extraction.
- Posez le module Requête API et reliez le nœud précédent à son entrée.
- Ouvrez-le, choisissez la Méthode et réglez le Timeout au plus court que votre service supporte.
- Saisissez l'URL, en insérant les variables depuis le panneau Variables disponibles.
- Renseignez les Entêtes, une par ligne, en général la ligne d'authentification fournie par le prestataire.
- Pour un POST ou un PUT, saisissez le Corps.
- Cliquez sur Ajouter une extraction et associez un Chemin JSON à un nom de Variable, autant de fois que de valeurs à récupérer.
- Cliquez sur Sauver, puis reliez OK vers la suite normale et Erreur vers un repli qui traite l'appel sans la donnée.
- Posez un module Débogage après la sortie OK, avec pour message les variables extraites, afin de lire ce qui a réellement été reçu.
- Cliquez sur Sauver, puis sur Appliquer les modifications dans le bandeau du haut.
- Appelez votre numéro, puis ouvrez le Journal de débogage du plan et vérifiez les valeurs extraites.
Si ça ne marche pas
Tous les appels partent en Erreur alors que l'URL fonctionne dans un navigateur. Un navigateur envoie vos cookies de session, pas le module. Vérifiez l'entête d'authentification. Vérifiez ensuite l'URL une fois les variables remplacées : un {{nom}} mal orthographié devient du vide et produit une adresse incomplète. Enfin, toute réponse hors de la famille des succès compte comme un échec, y compris une page d'erreur lisible.
La sortie Erreur est prise instantanément, sans que le service soit appelé. Le disjoncteur est ouvert : cinq échecs consécutifs vers ce serveur l'ont fait basculer pour trente secondes. Attendez une demi-minute avant de conclure, puis rappelez.
J'ai choisi 10 secondes et l'appel repart au bout de 8. Le délai est plafonné à huit secondes à l'exécution, quelle que soit la valeur choisie. C'est voulu : au-delà, l'appelant a déjà raccroché.
La variable extraite est vide alors que la réponse contient la donnée. Le chemin ne correspond pas. Les niveaux se séparent par des points, les listes se comptent à partir de zéro, et un chemin vide rapporte la réponse entière. Extrayez d'abord la réponse entière dans une variable, lisez-la dans le Journal de débogage, puis écrivez le chemin exact.
L'appel se coupe quand le service ne répond pas. La sortie Erreur n'est reliée à rien. Reliez-la, au minimum vers l'accueil habituel.
Comment le plan d'appel se construit, expliqué en images
Voir la page Plans de numérotation