Bruno, LE client API qui change le Game ?

Introduction

Les API sont devenues incontournables dans le développement d’applications modernes. Elles permettent de connecter des services entre eux et de récupérer des données de manière simple et efficace. Cependant, la gestion de ces API peut rapidement devenir un casse-tête, surtout lorsque l’on doit gérer de nombreuses collections d’API.

Les développeuses et développeurs sont souvent confrontés à des problèmes de documentation, de versioning, de sécurité ou encore de performances durant le développement de leurs applications.

Pour répondre à ces problématiques, il existe de nombreux outils sur le marché pour simplifier la vie des développeuses et développeurs. Le plus connu d’entre eux est sans doute Postman, qui permet de tester et de documenter des API de manière simple et efficace.

Mais alors, pourquoi parler de Bruno ? Qu’est-ce qui le différencie des autres outils du marché ? C’est ce que nous allons découvrir dans cet article !

Qu’est-ce que Bruno ?

Bruno est un outil open-source, qui vous vous en doutez, permet de gérer vos API de manière simple et efficace, et surtout de manière collaborative sans avoir besoin d’utiliser une enième plateforme tierce payante (Coucou Postman 👀).

La particularité de Bruno est qu’il est entièrement basé sur des fichiers, ce qui le rend très facile à manipuler et à versionner. Vous pouvez donc stocker vos collections d’API directement dans votre dépôt Git, et les partager avec vos collègues de manière transparente, c’est pas beau ça ?

Comment on l’installe ?

Pour installer Bruno, rien de plus simple, il vous suffit de lancer la commande qui va bien en fonction de votre Système d’Exploitation.

Je vous laisse découvrir les différentes méthodes d’installation sur le site officiel de Bruno.

Dans mon cas, j’ai utilisé Homebrew pour installer Bruno sur mon Mac.

# On Mac via Homebrew
brew install bruno

Démonstration

Création d’une collection

Commençons par démarrer le client graphique de Bruno et créons une nouvelle collection.

Comment faire une requête (GET) ?

Nous allons tester une requête sur l’API de API Adresses.

• Le endpoint: `https://api-adresse.data.gouv.fr/search’
• La méthode: GET
• Les paramètres: q=saint-malo

On ne peut pas faire plus simple, n’est-ce pas ?

Comment tester une requête ?

Bruno offre un moyen trés simple de tester vos requêtes. Il vous suffit de cliquer sur l’onglet Assert et d’écrire quelques assertions pour vérifier que votre requête retourne bien les données attendues.

La forme est relativement simple :

• res.status pour vérifier le code de statut de la réponse
• res.body pour vérifier le contenu de la réponse

Comment faire une requête (POST) ?

Nous allons tester une requête sur l’API de DummyJson.

• Le endpoint: https://dummyjson.com/products/add
• La méthode: POST
• Le body: {"title": "test1"}

Explorer une collections dans VSCode

Bruno permet d’exporter vos collections au format .bru ce qui vous permet de les explorer directement dans votre éditeur de code favori, et en plus il existe une extension pour VSCode qui permet de manipuler ces fichiers JSON hyper facilement !

Concrètement, les fichiers de notre collection ressemble à ça :

meta {
  name: API Adresse
  type: http
  seq: 2
}

get {
  url: https://api-adresse.data.gouv.fr/search/?q=saint-malo
  body: none
  auth: none
}

query {
  q: saint-malo
}

assert {
  res.status: eq 200
  res.body.type: eq FeatureCollection
  res.body: isJson
  res.body.limit: isNumber
  res.body.version: isString
}

La gestion des environnements

Bruno permet de gérer des environnements pour vos collections, ce qui vous permet de définir des variables globales que vous pouvez utiliser dans vos requêtes.

• Créons un nouvel environnement et stockons y notre URL de base.

• On constate que Bruno a créé un fichier Demo/environments/Env Demo.bru qui contient notre variable base_url.

vars {
  base_url: https://api-adresse.data.gouv.fr
}

• On peut maintenant utiliser cette variable dans notre requête avec la syntaxe {{base_url}}: {{base_url}}/search/?q=saint-malo

La gestion des secrets

Ok c’est bien beau tout ça, mais comment on fait en sorte de ne pas stocker nos secrets en clair dans nos fichiers de collections ?

Bruno permet de gérer des secrets de manière sécurisée en cochent la case Secret dans les variables de votre environnement.

La gestion des scripts

Bruno permet d’exécuter des scripts avant ou après l’exécution de vos requêtes. Cela peut être utile par exemple pour setter une variable à partir d’une réponse.

Voici un exemple de script en Post Response qui permet de stocker la valeur de res.body.type dans une variable test.

bru.setEnvVar("test", res.body.type);

Partager une collection

Pour partager une collection avec vos collègues, rien de plus simple, il vous suffit de pusher vos fichiers de collections dans un dépôt Git et de partager le lien vers votre dépôt, c’est aussi simple que ça !

Bonus: La CLI

Bruno propose également une interface en ligne de commande qui vous permet d’exécuter vos collections directement depuis votre terminal.

• Pour l’utiliser, il vous suffit de lancer la commande suivante :

npm install -g @usebruno/cli

• Puis d’exécuter votre collection (en utilisant notre environnement précédemment créé) :

bru run --env Demo

• Et voilà le résultat :

Running Folder Recursively

API Adresse (200 OK) - 142 ms
   ✓ assert: res.status: eq 200
   ✓ assert: res.body.type: eq FeatureCollection
   ✓ assert: res.body: isJson
   ✓ assert: res.body.limit: isNumber
   ✓ assert: res.body.version: isString

Requests:    1 passed, 1 total
Tests:       0 passed, 0 total
Assertions:  5 passed, 5 total
Ran all requests - 142 ms

• Vous pouvez également exporter le résultat de vos tests au format JSON en ajoutant l’option --output :

bru run --env Demo --output result.json

Conclusion

Bruno est un outil qui a le potentiel de changer la manière dont nous gérons nos collections d’API. Son approche basée sur des fichiers le rend très facile à manipuler et à versionner, et surtout très facile à partager avec vos collègues.

Nous n’avons vu qu’une petite partie des fonctionnalités de Bruno dans cet article, mais je vous invite à le tester par vous-même pour découvrir tout son potentiel.

La possibilité d’écrire directement au format .bru est un vrai plus pour les développeuses et développeurs qui aiment garder le contrôle sur leurs collections d’API, sans avoir à passer par une interface graphique.

Et puis, la petite CLI qui va bien pour exécuter vos collections directement depuis votre terminal ou votre pipeline CI/CD, c’est quand même la classe non ?

Postman a du souci à se faire, Bruno arrive pour changer le game 🔥