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 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. 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. 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.

Dans un corps oneOf à discriminateur, 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/* reçoit un champ par propriété, avec des champs fichier pour les parties binaires.
• L’urlencoded reçoit les mêmes champs, en texte.
• Un media type binaire reçoit un sélecteur de fichier.
• La famille texte, XML compris, reçoit un éditeur. Un corps XML démarre pré-rempli d’un document d’exemple généré.

Une dégradation à connaître : 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. Collez 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 plutôt qu’à la filtrer.

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é par les deux, puisqu’il décide du type d’éditeur du corps.

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, et le littéral n’est jamais envoyé. Taper {{ autocomplète depuis les variables en portée, chacune avec sa provenance. Les identifiants ont leurs propres conventions — voir Authentification & onboarding.

Sérialisation des paramètres

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 changent ce qui part du navigateur, et chacune reçoit 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, donc c’est la requête qui partirait vraiment. Le langage choisi est mémorisé d’une opération à l’autre.

Importer : cURL, Postman, HAR

Le dialogue d’import, dans la 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 plutôt que devinées.
• Collection Postman v2.1 — l’arborescence est aplatie, les variables de chemin substituées, et les corps raw/urlencoded/formdata/graphql ainsi que l’auth basic/bearer/apikey passent. Les variables de collection sont signalées plutôt que transformées en environnements.
• 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 présentée comme une ambiguïté à trancher, 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 stockés.

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 »
• collection Postman v2.1, qu’Insomnia importe nativement
• Markdown prêt pour une issue GitHub : requête, réponse, environnement, durée
• HAR 1.2

Les valeurs sensibles sont caviardées par défaut dans chaque format, et peuvent être incluses explicitement. Un secret porté par l’URL est masqué même quand l’encodage d’URL le transforme — une clé d’API en base64 s’y lit %2B, %2F et %3D. Il existe aussi un lien de partage par requête : il re-transforme les valeurs sensibles en {{var}} avant encodage, donc un lien collé ne transporte aucun jeton.

Un détail HAR : 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, par exemple une réponse cross-origin sans Timing-Allow-Origin ou une entrée archivée avant que le champ existe, le champ reste vide.

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. Chaque entrée offre deux actions : rejouer tel quel, qui renvoie à l’identique, et recharger dans la console, qui permet d’é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 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.

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. 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, tandis que 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. Le diagnostic est formulé 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 plutôt que des étiquettes. Un en-tête Link portant des relations next/prev reçoit un bouton qui charge la page voisine dans la console. 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. Sans Access-Control-Expose-Headers, le navigateur ne révèle qu’une courte liste, et le panneau prévient qu’elle peut être incomplète. Sans Timing-Allow-Origin, 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.

Ce que le navigateur refuse d’envoyer est nommé, au lieu d’échouer en silence. Un en-tête qu’aucune page n’a le droit de poser — Origin, Content-Length, tout en-tête Sec-, la liste complète du standard Fetch — est nommé sous les en-têtes dès que la requête le porte, et une opération TRACE indique que les navigateurs refusent la méthode. Un corps que le document déclare sur un GET ou un HEAD est affiché avec une note et laissé hors de l’envoi. Tout cela reste dans la commande cURL, qui est le moyen de l’envoyer. Une requête vers http://localhost ou 127.0.0.1 n’est jamais traitée de contenu mixte : les navigateurs l’autorisent depuis une page en https.

Trois 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 plutôt que comme un échec réseau, et n’écrit pas d’entrée d’historique.
• Les variables de serveur sont remplies. https://{region}.api.example.com envoie vers la valeur par défaut de la variable plutôt que vers un {region} littéral, et un environnement créé depuis ce serveur garde {{region}} parmi ses variables — changez-la une fois, et chaque requête suit.
• 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.