FR

Client HTTP

La fenêtre HTTP Client (barre d'outils du bas, icône globe) écrit et envoie les requêtes de votre API : collections, environnements, authentification, scripts et tests, historique. La fenêtre OpenAPI (à droite) montre la description d'API du projet et ouvre n'importe quelle opération dans le client HTTP.

Le client HTTP : une collection, une requête avec son script, la réponse

Collections et fichiers

Tout est en texte brut dans le projet, versionné et relu comme du code :

http-requests/<collection>/collection.json        nom, authentification, en-têtes, partage
http-requests/<collection>/http-client.env.json   les environnements
http-requests/<collection>/<dossier>/<requête>.http

New Request crée une requête dans la collection ; le bouton dossier ouvre une collection. Ctrl+Entrée envoie, Ctrl+S enregistre. L'onglet History garde ce qui a été envoyé.

Un fichier de requête est au format .http que lisent d'autres éditeurs (ligne de requête, en-têtes, ligne vide, corps), avec les réglages propres à l'IDE dans des commentaires # @ que ces éditeurs ignorent :

# @name Create a book
# @seq 2
# @auth jwt login=auth/login.http path=$.token var=token
# @no-redirect
# @insecure
# @timeout 30
POST {{baseUrl}}/api/books
Content-Type: application/ld+json

{"title": "Dune"}

> {%
  client.test("created", () => client.assert(response.status === 201));
  client.global.set("bookId", response.body.id);
%}

# @name et # @seq (l'ordre), # @no-redirect, # @insecure (accepter un certificat auto-signé) et # @timeout sont propres à une requête. Un script entre < {% … %} s'exécute avant la requête, un script après > {% … %} s'exécute après la réponse.

Environnements et variables

Environments… (la barre d'outils) modifie les environnements d'une collection (local, prod…) ; le sélecteur Library choisit celui qui sert.

La fenêtre Environments : une valeur secrète reste sur cet ordinateur

  • {{nom}} est remplacé par une variable d'environnement, une valeur posée par un script ou une connexion, ou une ligne @nom = valeur du fichier.
  • Valeurs dynamiques : {{$uuid}}, {{$timestamp}}, {{$isoTimestamp}}, {{$randomInt}}, {{$random.integer(1, 10)}}, {{$random.alphanumeric(8)}}, {{$random.email}}.
  • Secrets : cochez Secret sur une variable. Sa valeur, les jetons et les valeurs posées par les scripts restent sur cet ordinateur seulement (~/.jumphp/ide-http-secrets.json, lisible par vous seul) : jamais dans le projet, jamais envoyés à jumphp.net, masqués dans l'historique.

Authentification

Réglée sur la collection (Collection Settings…), héritée par ses requêtes, ou choisie par requête dans l'onglet Auth (# @auth) :

  • aucune, bearer, basic, clé d'API (en-tête ou paramètre) ;
  • JWT : une requête de connexion de la collection est envoyée, le jeton est lu dans sa réponse avec un JSONPath et gardé dans une variable ({{token}}). La connexion est envoyée quand il n'y a pas de jeton, quand il expire dans moins de 30 secondes, ou une fois de plus quand l'API répond 401 ;
  • OAuth2 : octroi client credentials ou password, le jeton gardé jusqu'à expires_in.

Forget the Tokens and Script Values dans l'onglet Auth repart de zéro.

Scripts et tests

Les scripts s'exécutent dans un Web Worker sans accès réseau, et s'arrêtent après 3 secondes. Disponibles : client.global.set / get, client.test(nom, fn), client.assert(cond, message), request.variables.set, req.setHeader / setBody / setUrl (avant la requête), response.status / body / headers / responseTime, expect(x).to.equal / eql / have.property / include / match / above / below / lengthOf, .not, jsonpath(data, chemin) et console.log. Les bru, res, req et test() de Bruno fonctionnent aussi. Snippets insère les plus courants ; l'onglet Tests de la réponse liste les résultats (2/2 tests).

La réponse

L'IDE envoie lui-même la requête (HTTP/1.1, gzip, chunked, cookies gardés par site jusqu'à la fermeture de l'IDE). Il montre le statut, le temps (connexion / TLS / attente / téléchargement), la taille, les en-têtes, les cookies, les résultats des tests et le corps : Pretty (JSON, XML, HTML), Raw, un Table (un tableau JSON, le member d'API Platform), un aperçu HTML (isolé) ou l'image. Un filtre JSONPath réduit le corps, Ctrl+F le fouille, Copy as curl copie la commande. La Timeline montre la chaîne de redirections. La seule chose envoyée à votre sujet est User-Agent: jumphp-ide, sauf si la requête en définit un.

L'aperçu dessine une réponse HTML comme le site le ferait : l'IDE récupère ses feuilles de style (avec leurs @import, polices et images url()), les images <img> / srcset, les images des styles en ligne et les icônes, relativement à l'adresse de la réponse, avec le réglage TLS et les cookies de la requête, et les met dans la page. Seul l'hôte de la page (et ses sous-domaines frères, ou localhost pour une page locale) est contacté, 8 Mo au plus par ressource ; les autres hôtes, les adresses privées et les redirections hors du site sont refusés. La note à côté de Reload resources liste ce qui n'a pas pu être chargé (survolez-la). Le cadre reste isolé ; Scripts (désactivé par défaut) exécute les scripts de la page.

Actualiser depuis l'API

Le bouton bleu Refresh from the API (OpenAPI / API Platform) de la barre d'outils rassemble tout ce que le projet dit de son API dans une seule collection organisée, API : un dossier par ressource (le nom court d'API Platform, ou le tag OpenAPI), une requête par opération dedans, triées (liste, lecture, création, remplacement, mise à jour, suppression, puis les opérations personnalisées), le login JWT dans auth/ quand lexik/jwt-authentication-bundle est installé (l'authentification de la collection), et un environnement dont {{baseUrl}} est l'adresse du site local (voir OpenAPI plus bas).

  • Avec API Platform, les requêtes sont faites à partir du code (le générateur de la fenêtre API Platform : corps d'exemple tirés des propriétés modifiables, filtres en paramètres de requête). Sinon elles viennent de la description OpenAPI : celle du site en marche, ou le fichier du projet (var/openapi.json après Regenerate the schema).
  • Relancer est sans danger : une requête que vous avez modifiée n'est jamais écrasée (la nouvelle version est écrite à côté, en *.theirs.http), les requêtes intactes suivent le code, les nouvelles opérations sont ajoutées et les requêtes intactes d'une opération disparue sont supprimées. Un résumé dit combien ont été ajoutées, mises à jour, conservées, supprimées, inchangées. Ce que l'outil a écrit est mémorisé par empreinte dans .apiplatform.json de la collection.

OpenAPI

La fenêtre OpenAPI : opérations, schémas, exemples

La description vient d'un fichier du projet (openapi.yaml|json, swagger.*) ou d'une adresse : /api/docs.jsonopenapi et /api/docs.json d'API Platform, /api/doc.json de NelmioApiDocBundle, sur l'adresse du site local du projet : le port de bin/jumphp web:serve (la configuration « Serve the site », y compris pour symfony-docker), le port publié du service PHP / web de votre propre fichier compose, sinon DEFAULT_URI / APP_URL du .env (un simple http://localhost n'est que le gabarit de Symfony : il passe en dernier). La fenêtre interroge chaque adresse candidate et garde celle qui répond. OpenAPI 3.x et Swagger 2.0, JSON ou YAML ; les $ref sont résolus, les allOf fusionnés, et un exemple est fabriqué à partir de chaque schéma.

  • La ligne sous l'adresse montre le site local (son adresse, en marche ou non). S'il est arrêté, Start the site lance la configuration d'exécution « Serve the site », et la description se charge toute seule dès que le site répond.
  • Regenerate the schema (API Platform, NelmioApiDocBundle) lance la console du projet, avec le lanceur de la fenêtre Console (Docker ou le PHP de l'ordinateur) : api:openapi:export --output=<fichier> ou nelmio:apidoc:dump --format=json, écrit le fichier (var/openapi.json par défaut, ou le fichier du projet saisi à côté du bouton, mémorisé) puis le charge : le schéma est disponible même site arrêté. Reload interroge à nouveau le site.
  • Search the operations filtre la liste ; chaque opération montre ses paramètres, son corps de requête, ses réponses et ses exemples.
  • Try it ouvre l'opération dans le client HTTP, déjà remplie : paramètres de chemin, paramètres de requête obligatoires, Accept et Content-Type, un corps d'exemple, et l'authentification de son schéma de sécurité (celle de la collection, si elle est bearer, JWT ou OAuth2).
  • Add All to the Collection écrit un fichier de requête par opération, un dossier par tag.
  • Accept a self-signed certificate sert pour un site local.

Import, export, partage

  • Import : fichiers .http (plusieurs requêtes séparées par ###), fichiers et dossiers Bruno .bru (avec leurs environnements), ou texte collé. Export d'une requête, d'un dossier ou d'une collection en .http ou .bru.
  • Share with the Project's Members… puis Sync Now : les fichiers vont au projet jumphp.net ; les membres les lisent, le propriétaire et les membres ayant l'accès en écriture les modifient. Un changement d'un côté passe de l'autre ; un fichier modifié des deux côtés garde la version de cet ordinateur et écrit l'autre à côté sous <nom>.theirs.http (jamais partagé). Les environnements voyagent sans leurs valeurs secrètes.

Limites

  • Les scripts n'ont pas de réseau et sont limités à 3 secondes.
  • Les requêtes sont envoyées en HTTP/1.1.
  • Les cookies sont gardés jusqu'à la fermeture de l'IDE.
  • Les secrets restent sur un seul ordinateur : chaque collègue renseigne les siens.