> For the complete documentation index, see [llms.txt](https://docs.augelab.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.augelab.com/french/function-blocks/blocks-reference/input-output/communication/rest-api-request.md).

# REST API - Request

Bloc unifié pour effectuer des requêtes REST vers des API web. Configurez la méthode, les headers, les query parameters et le payload. Choisissez le runtime Async (non-bloquant) ou Sync (attend la réponse). Optionnellement, extrayez une valeur du JSON de réponse en utilisant un chemin pointé/indexé.

## 📥 Entrées

* `Enable`\
  Booléen optionnel pour exécuter la requête. Si False, le bloc peut sauter l'envoi (par défaut True).
* `Server Address`\
  URL ou endpoint à appeler (obligatoire).
* `Headers`\
  Headers optionnels sous forme de dictionnaire ou de chaîne JSON.
* `Query Params`\
  Paramètres de requête optionnels sous forme de dictionnaire ou de chaîne JSON.
* `Payload`\
  Corps de la requête optionnel (sera envoyé selon le `Body Mode` sélectionné).
* `Response Path`\
  Chemin texte optionnel pour extraire une valeur depuis la réponse JSON (exemples : data.items\[0].id ou items\[2]).

(ici les sockets sont des entrées)

## 📤 Sorties

* `OK`\
  Booléen à True si la réponse HTTP indique un succès.
* `Status Code`\
  Code HTTP renvoyé par le serveur.
* `Error`\
  Message d'erreur pour problèmes réseau/HTTP ou erreurs de parsing.
* `Response Text`\
  Corps brut de la réponse en texte.
* `Response JSON`\
  Objet JSON parsé quand disponible (sinon None).
* `Response Headers`\
  Map des headers de la réponse.
* `Elapsed (ms)`\
  Durée de la requête en millisecondes.
* `Extracted Data`\
  Valeur résolue depuis `Response JSON` en utilisant `Response Path` (ou None si non trouvée).

(ici les sockets sont des sorties)

## 🕹️ Contrôles

* `Method`\
  Choix de la méthode HTTP : GET / POST / PUT / PATCH / DELETE.
* `Body Mode`\
  Mode d'envoi du `Payload` : json / form / raw.
* `Runtime Mode`\
  Mode d'exécution : Async (non-bloquant, conserve le dernier résultat) ou Sync (attend la réponse).
* `Timeout (s)`\
  Timeout en secondes pour la requête (valeurs invalides reviennent à une valeur par défaut sûre).
* `Verify SSL`\
  Activer ou désactiver la vérification du certificat TLS (désactiver uniquement en environnement de test de confiance).

## ⚙️ Comment ça marche

* Quand `Enable` est vrai, le bloc construit la requête en utilisant `Server Address`, `Headers`, `Query Params` et `Payload` avec la `Method` et le `Body Mode` choisis.
* En mode `Sync`, le bloc attend la fin de la requête HTTP et retourne le résultat dans le même cycle d'évaluation.
* En mode `Async`, le bloc envoie la requête sans bloquer ; il conserve le dernier résultat complété et met à jour les sorties lorsque la requête de fond se termine.
* Si un chemin JSON est fourni dans `Response Path`, il est résolu dans `Extracted Data` si présent ; chemin vide = pas d'extraction.
* En cas d'erreurs HTTP ou réseau, le bloc expose un message dans `Error` et marque le résultat comme invalide pour faciliter la détection des échecs.

## 📝 Utilisation

1. Renseignez `Server Address` avec votre endpoint API.
2. Fournissez éventuellement `Headers` et `Query Params` sous forme de dictionnaires ou de chaînes JSON.
3. Placez le corps de la requête dans `Payload` et choisissez le `Body Mode` (utilisez `json` pour des payloads structurés).
4. Choisissez le `Runtime Mode` :
   * Utilisez `Async` pour éviter de bloquer votre scénario (utile pour UI ou pipelines continus).
   * Utilisez `Sync` si vous avez besoin de la réponse immédiatement dans la même exécution.
5. (Optionnel) Ajoutez un `Response Path` pour extraire une valeur imbriquée du JSON de réponse à utiliser en aval.
6. Déclenchez l'appel en mettant `Enable` à True ou en alimentant un trigger booléen depuis d'autres blocs.

## 💡 Conseils et astuces

* Préparez les payloads JSON avec le bloc `Data to JSON` avant de les envoyer dans `Payload` pour une structure propre et moins d'erreurs de format.
* Utilisez `Parse Data Dictionary` après `Response JSON` pour accéder et router en toute sécurité aux champs de réponse si vous préférez une approche visuelle.
* Enregistrez les réponses ou résultats périodiques avec `CSV Export` pour garder un historique horodaté des réponses API.
* Pour déboguer, connectez `Error` ou `Response Text` à `Debug Input` pour imprimer ou inspecter des sorties inattendues.
* Combinez avec `Logic Input` ou `Rising Edge` pour contrôler précisément quand les requêtes sont envoyées (par exemple envoyer une seule fois par événement).

(here suggested blocks are from the provided list)

## 🛠️ Dépannage

* Server Address vide ou invalide : assurez-vous que `Server Address` est une URL complète (incluant le protocole si nécessaire).
* La requête expire : augmentez `Timeout (s)` ou vérifiez la connectivité réseau vers le serveur.
* Erreurs de vérification SSL en environnement de test : désactivez temporairement `Verify SSL` uniquement si vous faites confiance à la cible.
* Parsing JSON inattendu : inspectez d'abord `Response Text` ; envoyez un payload JSON valide et réglez `Body Mode` sur `json` pour données structurées.
* Pas de donnée extraite : vérifiez la structure dans `Response JSON` et ajustez `Response Path` en utilisant la notation point/index (ex. items\[0].id).

## 🔒 Confidentialité et sécurité

Faites attention aux données sensibles dans `Headers` ou `Payload` (clés API, mots de passe). Lors de la journalisation ou de l'export, veillez à masquer ou supprimer les champs sensibles.

## 🧭 Exemples de workflows

* Envoyer périodiquement des données de capteurs vers un service web et enregistrer les comptages de succès/échec avec `CSV Export`.
* Poster un objet JSON structuré créé par `Data to JSON` puis utiliser `Extracted Data` dans un flux décisionnel (`Logic Input` / seuils).
* Utiliser `Debug Input` pour inspecter les erreurs serveur en développement avant de passer au logging de production.