API

Certaines parties de votre site répondent à des requêtes au lieu d’afficher une page : un formulaire de contact qui enregistre un message, une page de paiement qui demande un paiement à Stripe, une tâche qui envoie les rappels du lendemain. Chacune correspond à une route dans le code de votre site. La vue API vous permet de toutes les tester sans quitter l’éditeur.

Ouvrir la vue API

Lorsque votre site contient des routes, un sélecteur Pages | API apparaît en haut du panneau Pages. Cliquez sur API pour les voir.

La liste est organisée comme celle de vos pages, avec un niveau par partie de l’adresse :

• Une route qui ne répond qu’à une méthode affiche celle-ci sur sa ligne, par exemple GET à côté de health. Cliquez sur la ligne pour l’ouvrir.
• Une route qui répond à plusieurs méthodes se déplie en une ligne par méthode, comme GET, POST et DELETE.
• Les dossiers regroupent les routes dont les adresses commencent de la même façon.
• Le plan de site, le fichier robots.txt, le manifeste de l’application et les images de partage sur les réseaux sociaux sont aussi répertoriés, car votre code les génère.

Sur un site qui contient beaucoup de routes, un champ Filtrer les points de terminaison apparaît en haut.

Vous pouvez aussi saisir une adresse qui commence par /api/ dans la barre d’adresse en haut de l’éditeur, ou choisir une route dans la liste qui s’ouvre en dessous. Saisir une adresse complète comme /api/tools/figma ouvre la route et remplit figma pour vous.

Sur téléphone, ouvrez le menu du site en haut et choisissez API, ou sélectionnez une route dans la liste des pages.

Envoyer une requête

Choisissez une méthode pour afficher la vue API dans la zone de travail. L’adresse en haut indique exactement ce qui sera envoyé et se met à jour à mesure que vous remplissez les champs.

• Aperçu envoie la requête à la version que vous êtes en train de créer. En ligne l’envoie à votre site publié.
• Envoyer envoie la requête. ⌘↵ / Ctrl+Enter fonctionne aussi.

Paramètres

Ce sont les valeurs que la route lit dans son adresse. Les valeurs de Chemin correspondent aux parties entre crochets, comme [id], et portent la mention Obligatoire. Les valeurs de Requête sont celles que la route recherche après ?. Cliquez sur Ajouter un paramètre pour en envoyer un qui n’est pas répertorié.

Corps

Pour POST, PUT, PATCH et DELETE. Les champs que la route lit sont déjà répertoriés : remplissez-les comme un formulaire. Passez à JSON pour écrire vous-même le corps. Si la route lit un formulaire, elle reçoit des champs de formulaire, envoyés comme le ferait un navigateur.

En-têtes

Des informations supplémentaires envoyées avec la requête, comme un jeton de connexion. Cliquez sur Ajouter un en-tête pour en ajouter un.

Lire la réponse

Le statut s’affiche en premier, avec la durée de la requête et la taille de la réponse. En dessous :

• Corps affiche le contenu reçu sous une forme lisible : JSON coloré, XML et HTML mis en forme (avec une vue Page pour le HTML), un tableau pour le CSV et des images pour les fichiers image.
• En-têtes répertorie les en-têtes renvoyés par la route.
• Console affiche ce que le serveur de votre site a écrit pendant le traitement de la requête. Cela fonctionne pour les requêtes envoyées à l’aperçu.

Une route qui renvoie un fichier, comme un export CSV ou une image générée, affiche un bouton Télécharger. Une route qui redirige les visiteurs indique la destination, avec Ouvrir la page s’il s’agit d’une page de votre site.

Cliquez sur l’horloge pour voir les requêtes envoyées pendant cette session et rouvrir celle de votre choix.

En cas de problème

Si votre code échoue pendant le traitement d’une requête, la vue API affiche l’erreur et la ligne de code concernée.

• Ouvrir le code ouvre ce fichier dans l’éditeur de code.
• Corriger avec l’IA lance une discussion contenant l’erreur et ce que votre serveur a écrit, pour que l’IA puisse la corriger.

Requêtes authentifiées

Certaines routes ne répondent qu’aux personnes connectées. Envoyez d’abord une requête à la route de connexion de votre site, avec une adresse e-mail et un mot de passe de votre site : la vue API conserve les cookies définis par votre site et les envoie avec les requêtes suivantes, comme un navigateur. Ils apparaissent dans En-têtes sous Cookie, avec Effacer pour vous déconnecter.

Vous pouvez aussi ajouter vous-même un en-tête Authorization si vos routes utilisent des jetons.

Tâches planifiées et paiements

Vous n’avez aucun secret à copier pour les tester :

• Les routes qui s’exécutent selon une planification vérifient un secret conservé par votre site. La vue API l’envoie pour vous.
• Les webhooks Stripe vérifient une signature. La vue API préremplit le corps avec un événement de test Stripe et le signe avec le secret de votre site. Les événements de test signés sont envoyés uniquement à l’Aperçu : un test n’agit donc jamais sur les commandes réelles de votre site en ligne.

Ajouter une route

Cliquez sur + en haut du panneau Pages lorsque vous êtes dans API. Si vous êtes dans Pages, choisissez Nouveau point de terminaison dans le menu.

• Chemin est l’adresse de la route après /api/. Utilisez [id] pour une partie variable, comme tools/[id]/reviews.
• Méthodes correspond aux méthodes auxquelles la route répond. Choisissez-en autant que nécessaire.
• Description permet à l’IA d’écrire la route dans une nouvelle discussion. Fichier vide crée un fichier vierge dans lequel vous écrivez vous-même le code.

La nouvelle route s’ouvre dans la vue API dès sa création, pour que vous puissiez la tester immédiatement.

Bon à savoir

• Une requête dispose de 12 secondes. Si une route envoie encore des données passé ce délai, la vue affiche ce qui a été reçu jusque-là.
• La vue API affiche jusqu’à 512 KB d’une réponse, et les fichiers jusqu’à 5 MB peuvent être téléchargés.
• Vous pouvez avoir 3 requêtes en cours à la fois et en envoyer jusqu’à 30 par minute.
• Vos requêtes, votre historique et vos cookies sont conservés jusqu’au rechargement de l’éditeur.
• Pour envoyer une requête à la version En ligne, votre site doit être publié.