Chaque requête, expliquée de bout en bout.

Chaque page d’opération porte un panneau qui envoie de vraies requêtes fetch depuis le navigateur du lecteur, en mesure la durée et affiche la réponse. Ce guide est la référence technique de ce panneau ; la page de fonctionnalité plante le décor, et Console d’essai & CORS explique pourquoi une requête correcte peut quand même être bloquée.

Le formulaire vient du schéma

Chaque type déclaré a son champ — et là où aucun formulaire n’aurait de sens, le corps JSON brut reste la porte de sortie :

Les champs restent typés texte, même pour les nombres et les dates, à dessein : un champ natif refuserait un {{var}}, et une variable doit rester saisissable partout. Les valeurs sont converties vers leur type déclaré à l’envoi, et le placeholder montre l’exemple déclaré quand il existe. Un corps oneOf à discriminateur reçoit un sélecteur de variante : changer de variante retire les clés de l’autre, et la propriété discriminante se remplit toute seule, en lecture seule.

La nature du corps suit le media type sélectionné : un JSON reçoit un éditeur texte plus des champs structurés, multipart/* un champ par propriété avec fichier pour les parties binaires, l’urlencoded les mêmes champs en texte seul, un media type binaire un sélecteur de fichier, et la famille texte (XML compris) un éditeur — un corps XML démarre pré-rempli d’un document d’exemple généré. Une dégradation assumée : une propriété format: binary sous urlencoded devient un champ texte, parce qu’une valeur de formulaire pourcent-encodée ne peut pas transporter un fichier — on colle la valeur encodée à la place.

La validation du corps est volontairement minimale : JSON bien formé plus présence des champs required de premier niveau, vérifiés après interpolation des {{var}}. Le formulaire aide à construire la requête ; il ne s’interpose jamais entre vous et l’envoi d’une expérience.

Une requête, deux éditeurs

La requête s’édite depuis la colonne centrale de doc comme depuis le panneau, et les deux montrent toujours la même requête — modifiez un champ d’un côté, l’autre suit. Le media type est un choix unique partagé : puisqu’il décide du type d’éditeur, deux colonnes libres de diverger documenteraient et éditeraient deux corps différents.

Dans un corps JSON, un {{var}} peut rester hors guillemets ("petId": {{petId}}) : la valeur interpolée arrive en nombre, pas en chaîne. Une variable manquante bloque l’envoi avec un signal visible — le littéral n’est jamais envoyé — et taper {{ autocomplète depuis les variables en portée, chacune avec sa provenance. Les identifiants ont leurs propres conventions : voir Authentification & onboarding.

La sérialisation, les parties ingrates

style et explode sont résolus avec leurs défauts de la spec (form en query et cookie, simple en path et header) et appliqués à l’envoi : un tableau query éclaté répète la paire (?tags=cat&tags=dog), les formes non éclatées joignent sur le délimiteur du style, deepObject met chaque propriété entre crochets (?owner[city]=Lyon), et les styles de chemin label/matrix ajoutent leur préfixe. Trois déclarations qui changent ce qui part du navigateur reçoivent un badge visible dans la doc :

• allowReserved — les caractères réservés passent sans encodage ; une espace devient %20, jamais +.
• allowEmptyValue — ?verbose= est une valeur en soi, envoyée via une bascule explicite ; un champ vide continue de signifier « ne pas envoyer ».
• Les paramètres in: cookie — édités comme les autres, repliés dans un unique en-tête Cookie. Les navigateurs ignorent un en-tête Cookie posé par un script, et le panneau le dit sous les champs ; l’en-tête atteint quand même l’export cURL et les extraits, ce qui est en général la raison de sa présence.

Des extraits en dix langages

Chaque requête se rend en extrait vivant : cURL, fetch, Node, Python, PHP, Ruby, Java, C#, Go et HTTPie. L’extrait suit ce que vous tapez — c’est la requête qui partirait vraiment — et le langage choisi est mémorisé d’une opération à l’autre.

Importer : cURL, Postman, HAR

Le dialogue d’import (barre d’outils d’en-tête) transforme une requête écrite ailleurs en console pré-remplie. Il n’envoie rien et n’écrit rien de lui-même.

• cURL — collez la commande ; le parseur comprend -X, -H, la famille -d/--data*, --data-urlencode, -F, -u, --url, -G et les arguments courts attachés (-XPOST). Les options inconnues sont listées comme ignorées, jamais devinées.
• Collection Postman v2.1 — l’arborescence est aplatie, les variables de chemin substituées ; les corps raw/urlencoded/formdata/graphql et l’auth basic/bearer/apikey passent. Les variables de collection sont signalées, jamais transformées en environnements dans votre dos.
• HAR — une entrée par requête enregistrée ; les cookies enregistrés sont écartés, avec un avertissement.

La détection du format lit le contenu, pas l’extension du fichier. L’appariement au schéma retire les préfixes de serveurs connus et note chaque opération au nombre de segments littéraux alignés ; une égalité est une ambiguïté que le dialogue présente au lieu de trancher en silence, et tout ce qui ne s’importe pas est listé avant que vous validiez. Un identifiant reconnu devient la variable conventionnelle auth.X en portée de session — sensible, caviardée dans l’historique, et jamais écrite dans vos environnements : une valeur collée depuis le terminal de quelqu’un d’autre n’est pas à vous.

Exporter : quatre formats, caviardés par défaut

Toute requête — du panneau ou de l’historique — s’exporte en commande cURL copiable (multi-lignes, avec une bascule « substituer les variables »), en collection Postman v2.1 (qu’Insomnia importe nativement), en Markdown prêt pour une issue GitHub (requête, réponse, environnement, durée), ou en HAR 1.2. Les valeurs sensibles sont caviardées par défaut dans chaque format, et le rester est un choix explicite. Il existe aussi un lien de partage par requête : il re-transforme les valeurs sensibles en {{var}} avant encodage — un lien collé ne transporte jamais un jeton.

Un détail HAR qui compte : httpVersion porte le protocole que l’instantané de transfert a réellement observé — http/1.1, h2, h3 — jamais une valeur devinée. Quand le protocole ne peut pas être connu (réponse cross-origin sans Timing-Allow-Origin, entrée archivée avant que le champ existe), le HAR ne dit rien plutôt que quelque chose de plausible.

L’historique : rejouer, recharger, borné

Chaque requête envoyée écrit une entrée IndexedDB : requête résolue, réponse, durée, environnement, et la liste des valeurs sensibles utilisées — c’est elle qui rend possible le caviardage à l’affichage et à l’export. La liste se filtre par endpoint, environnement, statut et texte libre, et chaque entrée offre deux actions : rejouer tel quel (renvoyer, à l’identique) et recharger dans la console (éditer d’abord). Au-dessus du panneau de réponse, un sélecteur liste les appels passés de l’opération affichée ; en choisir un montre sa réponse archivée sans rien renvoyer.

Le même historique nourrit aussi deux vues en lecture seule dans la doc elle-même : un bandeau des appels récents en bas de chaque page d’opération (heure, statut, durée, environnement), et une carte des endpoints les plus utilisés sur la vue d’ensemble, classée sur les propres compteurs du lecteur — les deux chiffres qu’une page sans backend peut honnêtement afficher, puisqu’il n’y a aucune télémétrie à agréger.

La rétention, c’est history.maxEntries (500 par défaut) et history.maxAgeDays (30), au premier seuil atteint, purgée à l’écriture et énoncée dans le dialogue — une éviction silencieuse ressemble à une perte de données. Les corps au-delà de 256 Ko sont tronqués, avec un indicateur visible. Les fichiers envoyés n’atteignent jamais le stockage : seuls nom, taille et type sont retenus — rejouer est donc désactivé sur une telle entrée (renvoyer posterait une légende, pas un fichier), recharger reste possible : c’est là qu’on re-choisit le fichier.

Quand ça échoue, et quand ça réussit

Un envoi raté est diagnostiqué dans le panneau — hors ligne, contenu mixte, CORS ou hôte injoignable, au conditionnel (« le plus probable »), parce que le navigateur cache les détails à la page. Une réponse réussie voit ses en-têtes lus pour vous : limites de débit, Retry-After, Deprecation et Sunset, pagination Link, validateurs ETag et Last-Modified, identifiants de corrélation, plus protocole, compression et cache.

Deux de ces lectures sont des boutons, pas seulement des étiquettes : un en-tête Link portant des relations next/prev reçoit un bouton qui charge la page voisine dans la console, et une réponse porteuse de validateurs offre un rejeu conditionnel — la même requête renvoyée avec If-None-Match/If-Modified-Since, en attendant un 304 (GET et HEAD uniquement).

En cross-origin, deux en-têtes de réponse débloquent la matière complète : Access-Control-Expose-Headers (sans lui le navigateur ne révèle qu’une courte liste, et le panneau prévient que la liste peut être incomplète) et Timing-Allow-Origin (sans lui les tailles de transfert lisent zéro et les puces compression et cache restent cachées). Les deux sont couverts dans Console d’essai & CORS.

Deux détails qui comptent

• Une requête en vol s’annule. Un contrôle Annuler accompagne Envoyer tant qu’une requête est dehors ; une annulation est annoncée comme une information, pas rendue comme un échec réseau, et n’écrit pas d’entrée d’historique.
• Le serveur le plus spécifique gagne. Une opération qui déclare ses propres servers les garde ; la base URL d’un environnement ne remplace que le serveur racine. La base URL affichée est celle que l’envoi frappera.