Anatomie

Le composant comprend trois zones. Une barre d'en-tête contient le sélecteur d'endpoint (dropdown animé par AnimatePresence), la barre d'URL affichant base + chemin, et le bouton Exécuter avec état de chargement. En dessous, une zone de contenu se divise en deux colonnes quand l'endpoint sélectionné possède un body : colonne gauche pour le JSON body, colonne droite pour la réponse. Sans body, la réponse occupe toute la largeur. Un badge pill avec icône Braces se positionne au-dessus du titre comme marqueur de catégorie.

Comment ça marche

L'état est géré par quatre booléens : isRunning, showResponse, copied et showEndpointList. Appuyer sur Exécuter passe isRunning à true et showResponse à false, puis un setTimeout de 800ms inverse les deux. Le panneau de réponse utilise AnimatePresence en mode wait pour fondre entre trois états nommés : 'loading' (spinner centré), 'response' (apparition depuis y+8), et 'empty' (texte indicatif atténué). Le tokeniseur JSON est un parseur caractère par caractère qui identifie clés, valeurs string, nombres et booléens via regex, et retourne un tableau de segments colorés rendus en spans inline dans un élément pre avec numéros de ligne.

Comment le coder en React

1. Définir la structure de données des endpoints

   Crée une interface ApiEndpoint avec method, path, label, un body string optionnel et un response string. La réponse est du JSON pré-sérialisé, cela garde le composant purement présentationnel et évite tout appel réseau réel dans la démo.

   interface ApiEndpoint {
     method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
     path: string;
     label: string;
     body?: string;
     response: string;
   }

2. Construire le dropdown d'endpoint animé

   Bascule showEndpointList avec le bouton sélecteur. Enveloppe la liste déroulante dans AnimatePresence et anime-la avec opacité et un décalage y de 4px. Au clic sur un item, mets à jour selectedIdx, ferme la liste et réinitialise showResponse pour que l'ancienne réponse ne persiste pas.

   <AnimatePresence>
     {showEndpointList && (
       <motion.div
         initial={{ opacity: 0, y: -4 }}
         animate={{ opacity: 1, y: 0 }}
         exit={{ opacity: 0, y: -4 }}
         transition={{ duration: 0.15 }}
         style={{ position: "absolute", top: "calc(100% + 4px)", zIndex: 50 }}
       >
         {endpoints.map((ep, i) => (
           <button key={i} onClick={() => {
             setSelectedIdx(i);
             setShowEndpointList(false);
             setShowResponse(false);
           }}>
             {ep.label}
           </button>
         ))}
       </motion.div>
     )}
   </AnimatePresence>

3. Simuler le cycle chargement / réponse

   Le callback handleRun passe isRunning à true et efface showResponse, puis se résout après 800ms. Dans le panneau de réponse, utilise AnimatePresence avec mode='wait' et trois enfants nommés pour que React démonte complètement un état avant d'en monter un autre.

   const handleRun = useCallback(() => {
     setIsRunning(true);
     setShowResponse(false);
     setTimeout(() => {
       setIsRunning(false);
       setShowResponse(true);
     }, 800);
   }, []);

4. Écrire le tokeniseur de syntaxe JSON

   Implémente tokenizeLine comme une boucle while qui match les patterns de gauche à droite : clé JSON (mot entre guillemets suivi de deux-points), valeur string, entier ou booléen/null. Chaque match pousse un segment avec texte et couleur CSS. Rends les segments en spans colorés dans un bloc pre, avec une colonne de numéros de ligne via map sur les lignes splitées.

   function tokenizeLine(line: string): TokenSegment[] {
     const segments: TokenSegment[] = [];
     let remaining = line;
     while (remaining.length > 0) {
       const keyMatch = remaining.match(/^("[w_]+")(s*:s*)/);
       if (keyMatch) {
         segments.push({ text: keyMatch[1], color: "var(--color-accent)" });
         segments.push({ text: keyMatch[2], color: "var(--color-foreground-muted)" });
         remaining = remaining.slice(keyMatch[0].length);
         continue;
       }
       // ... string, number, boolean matches
     }
     return segments;
   }

Quand l'utiliser

Utilise ce composant sur les landing pages de produits développeur, les sites de documentation API ou les pages d'onboarding SaaS où montrer un cycle de requête en direct construit la confiance plus vite qu'un simple bloc de code. Il fonctionne particulièrement bien quand ton API retourne du JSON propre et que tu veux mettre en avant des endpoints spécifiques. Évite-le sur les pages marketing grand public où le cadrage technique désorienterait des visiteurs non développeurs, et ne l'utilise pas comme vrai client HTTP, c'est une démo présentationnelle, pas une couche réseau.

Utilisé par

• Stripe, La référence API Stripe intègre des panneaux requête/réponse interactifs pour chaque endpoint, avec badges de méthode HTTP colorés et réponses JSON copiables.
• Postman, L'interface web de Postman a popularisé la mise en page sélecteur d'endpoint + barre d'URL + panneau de réponse que ce composant distille en section intégrable.
• Resend, La documentation de Resend utilise des explorateurs API en panneau divisé avec code couleur des méthodes HTTP et prévisualisations JSON colorées.
• Supabase, Supabase expose des playgrounds API en direct dans sa documentation, permettant aux développeurs de lancer de vraies requêtes depuis la page de doc elle-même.

FAQ