winzik/docs/ide/fr/http-client.md

150 lines
10 KiB
Markdown

# 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](../images/http-client-request.png)
## 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 :
```http
# @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](../images/http-client-environments.png)
- `{{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](../images/http-client-openapi.png)
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.