150 lines
10 KiB
Markdown
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.
|
|
|
|

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

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