# Bibliothèque `requeto` — requêtes HTTP — v1.0.0

Source : https://docs.berkios.online/modules/requeto/ · Section : Modules · Documentation officielle BERKIOS (https://docs.berkios.online)


8 commandes pour appeler une API HTTP(S) depuis BERKIOS CODE sans répéter les mêmes lignes : **adresse vérifiée**, **extraction JSON avec valeur par défaut**, **réponse JSON indentée**, **paramètres d'adresse encodés** et **cache temporisé**.
Chaque commande existe en **français**, **anglais** et **espagnol**. Permissions demandées : `reseau` (commande intégrée `requete`) et `stockage` (cache : `stocker`, `lire`, `oublier`).
Ce sont de simples macros vers les commandes intégrées `requete`, `extraire`, `valider-json`, `formater-json`, `encoder-url`, `stocker`… : le Studio et l'application Flutter se comportent donc de la même façon.

## Une requête en quatre lignes

```text
quand clic
  set "$u" "https://jsonplaceholder.typicode.com/posts"
  parametre-url "$u" "userId" "Champ_utilisateur"       # ignoré si le champ est vide
  obtenir "$u" "$reponse"
  champ-ou "$reponse" "0.title" "(aucun résultat)" "Titre"
```

`parametre-url` ajoute `?userId=1` (ou `&userId=1` s'il y a déjà des paramètres) ; nom et valeur sont encodés. Avec `obtenir-cache "$u" 60 "$reponse"`, la réponse à cette adresse est relue pendant 60 secondes sans nouvelle requête.

## Commandes

| Noms (fr · en · es) | Syntaxe | Effet |
|---|---|---|
| `obtenir` · `get-url` · `obtener` | `obtenir "https://…" "Résultat"` | Requête GET : vérifie que l'adresse est http(s), puis écrit le corps de la réponse dans le résultat. L'adresse peut être un texte, un composant ou une $variable ; {variable} et {variable:url} y sont remplacés. |
| `obtenir-json` · `get-json` · `obtener-json` | `obtenir-json "https://…" "chemin.dans.le.json" "Résultat"` | Requête GET puis extraction d'un champ du JSON reçu (« items.0.nom »). Texte vide si le champ est absent ; erreur si la réponse n'est pas du JSON. |
| `obtenir-formate` · `get-pretty` · `obtener-formateado` | `obtenir-formate "https://…" "Résultat"` | Requête GET ; si la réponse est du JSON, elle est écrite indentée (lisible dans un champ de texte), sinon telle quelle. |
| `champ-ou` · `field-or` · `campo-o` | `champ-ou "$reponse" "chemin" "valeur par défaut" "Résultat"` | Lit un champ d'un JSON déjà reçu (chemin à points, indices de tableau permis) ; écrit la valeur par défaut quand le champ est absent, null ou vide, ou quand la source n'est pas du JSON valide (sans erreur). |
| `parametre-url` · `url-param` · `parametro-url` | `parametre-url "$url" "nom" "valeur"` | Ajoute « nom=valeur » (nom et valeur encodés) à l'adresse contenue dans la variable : « ? » si elle n'a pas encore de paramètres, « & » sinon. Si le nom ou la valeur est vide, l'adresse reste inchangée (filtre facultatif d'un formulaire). Peut être répété. |
| `obtenir-cache` · `get-cached` · `obtener-cache` | `obtenir-cache "https://…" 60 "Résultat"` | GET avec cache : si la réponse mémorisée pour cette adresse a moins de N secondes, elle est relue sans requête ; sinon la requête est faite et mémorisée. Le cache est propre à chaque adresse (paramètres compris) ; N = 0 le désactive. |
| `age-cache` · `cache-age` · `edad-cache` | `age-cache "https://…" "Résultat"` | Écrit l'âge en secondes de la réponse mémorisée par obtenir-cache pour cette adresse (0 = obtenue à l'instant), ou -1 s'il n'y en a pas. |
| `vider-cache` · `clear-cache` · `vaciar-cache` | `vider-cache "https://…"` | Oublie la réponse mémorisée par obtenir-cache pour cette adresse : le prochain appel refera la requête. |

L'adresse d'une commande `obtenir*` peut être un texte, un composant ou une `$variable`. Dans le texte, `{variable}` est remplacé par sa valeur et `{variable:url}` par sa valeur **encodée** (comme avec la commande intégrée `requete`). Pour assembler base et chemin, `parametre-url` se combine avec les commandes intégrées `joindre-url "Base" "Chemin" "Résultat"`, `extraire-parametre-url` et `valider-json`.

## Ce que fait la bibliothèque
- **Adresse vérifiée** : `obtenir`, `obtenir-json`, `obtenir-formate` et `obtenir-cache` refusent, **avant toute requête**, une adresse qui n'est pas `http://` ou `https://` (`file:`, `ftp:`, `javascript:`, texte libre…) avec le message « Requeto : adresse http(s) invalide. ».
- **Erreur réseau** : le script s'arrête sur la ligne en cause avec le message de l'hôte ; les lignes suivantes ne sont pas exécutées.
- **`champ-ou`** : la valeur par défaut est écrite quand le champ est absent, `null` ou vide, ou quand la source n'est pas du JSON valide (page d'erreur HTML, texte…) — sans interrompre le script ; `0` et `false` sont de vraies valeurs et sont conservées. À l'inverse, `obtenir-json` s'arrête avec une erreur si la réponse n'est pas du JSON.
- **`parametre-url`** : si le nom ou la valeur est vide, l'adresse reste inchangée — pratique pour des filtres facultatifs de formulaire. L'adresse ne doit pas déjà se terminer par `?` ou `&`.
- **`obtenir-cache "adresse" N "Résultat"`** : mémorise la réponse et l'instant de la requête sous `requeto:<adresse>` et `requeto:<adresse>:t` (commande intégrée `stocker`, qui persiste d'une session à l'autre quand l'hôte le permet). Si la réponse à **cette adresse** (paramètres compris) a moins de `N` secondes, elle est relue sans requête ; `N = 0` désactive le cache. Deux adresses différentes ne partagent jamais d'entrée. `age-cache "adresse" "Résultat"` donne l'âge de l'entrée (secondes, `-1` si absente) ; `vider-cache "adresse"` oublie l'entrée ; il n'existe pas de « tout vider » (BERKIOS CODE ne sait pas lister les clés mémorisées).
- **`obtenir-formate`** : la réponse est indentée seulement si c'est du JSON valide, sinon elle est écrite telle quelle.

## Limites assumées
- **GET uniquement.** La seule commande réseau de BERKIOS CODE est `requete`, qui fait un GET sans en-têtes ni corps. Requeto n'ajoute donc ni POST/PUT/PATCH/DELETE, ni en-têtes (`Authorization`, `X-API-Key`), ni lecture du **code HTTP** ou des en-têtes de réponse. Les commandes `http-post`, `http-put`… du registre système sont des commandes du Bridge, pas encore appelables depuis le code d'un composant.
- **Pas de secret dans l'adresse.** Une clé passée en paramètre (`?api_key=…`) apparaît dans l'adresse, les journaux des serveurs et l'historique réseau ; n'y mettez que des clés publiques ou à portée limitée.
- **Pas de nouvel essai automatique** : une erreur arrête le script, elle ne peut pas être interceptée.
- **Navigateur** : dans le Studio web, l'API appelée doit autoriser CORS ; l'application Flutter n'a pas cette contrainte.
- Le cache stocke la réponse brute : ne pas y mettre de données sensibles.
- Tests : `studio/tests/library-requeto.test.ts` (réseau simulé). Aucun appel à une vraie API n'a été fait pendant le développement.