# curl, Bruno et Postman

Pour parler à une API, pas besoin d'écrire du code : des outils permettent d'envoyer des requêtes HTTP à la main.

### curl

`curl` est l'outil en ligne de commande de référence. Il est installé par défaut sur Linux, macOS et Windows 10+.

```bash
curl http://api-ritif.portlatch.com/v1/cocktails
```

#### Les options utiles

<table id="bkmrk-optionr%C3%B4le--iaffiche"><thead><tr><th>Option</th><th>Rôle</th></tr></thead><tbody><tr><td>`-i`</td><td>Affiche les headers de la réponse</td></tr><tr><td>`-v`</td><td>Mode verbeux : affiche toute la requête et toute la réponse</td></tr><tr><td>`-X METHODE`</td><td>Choisit la méthode HTTP (`-X DELETE`)</td></tr><tr><td>`-H "Nom: valeur"`</td><td>Ajoute un header</td></tr><tr><td>`-d '...'`</td><td>Envoie un body (et passe en `POST` par défaut)</td></tr><tr><td>`--json '...'`</td><td>Envoie du JSON, avec les headers `Content-Type` et `Accept` adaptés</td></tr><tr><td>`-s`</td><td>Mode silencieux (masque la barre de progression)</td></tr></tbody></table>

#### Exemples

```bash
# Lire les headers de la réponse
curl -i http://api-ritif.portlatch.com/v1/cocktails/3

# Envoyer du JSON
curl -i -X POST http://api-ritif.portlatch.com/v1/orders \
  -H "Content-Type: application/json" \
  -H "X-API-Key: votre-cle" \
  -d '{"cocktail_id": 3}'

# La même chose, en plus court
curl -i http://api-ritif.portlatch.com/v1/orders \
  -H "X-API-Key: votre-cle" \
  --json '{"cocktail_id": 3}'

# Supprimer
curl -i -X DELETE http://api-ritif.portlatch.com/v1/orders/42 -H "X-API-Key: votre-cle"
```

<p class="callout info">Pour rendre le JSON lisible, passez la réponse dans un formateur : `curl -s ... | python3 -m json.tool` ou `curl -s ... | jq`.</p>

<p class="callout warning">Sous Windows PowerShell, `curl` peut être un alias vers `Invoke-WebRequest`, qui n'a pas les mêmes options. Utilisez `curl.exe`, ou Git Bash.</p>

<p class="callout warning">Plutôt que de copier votre clé dans chaque commande, stockez-la dans une variable : `export KEY=votre-cle`, puis `-H "X-API-Key: $KEY"`.</p>

### Bruno

[Bruno](https://www.usebruno.com) est un client d'API graphique, open source et sans compte. On y enregistre ses requêtes dans des **collections**.

Sa particularité : une collection est un **dossier de fichiers texte**. On peut donc la versionner dans git et la partager avec son équipe comme du code.

#### Prise en main

- Installez Bruno depuis [usebruno.com/downloads](https://www.usebruno.com/downloads).
- Créez une collection `api-ritif` dans un dossier de votre choix.
- Créez un **environnement** avec deux variables : `baseUrl` = `http://api-ritif.portlatch.com/v1` et `apiKey` = votre clé.
- Créez une requête `GET {{baseUrl}}/cocktails` et envoyez-la.
- Dans l'onglet **Headers** d'une requête, ajoutez `X-API-Key: {{apiKey}}`.

### Et Postman ?

Postman est le client d'API le plus connu, et vous le croiserez sûrement en entreprise. Il fonctionne sur le même principe que Bruno.

<p class="callout info">On ne l'utilise pas dans ce cours : il demande un compte, et stocke les collections dans son cloud plutôt que dans votre dépôt git.</p>