Bruno est-il Request-First ? Choisir un outil Design-First

Bruno est-il orienté requêtes ? Oui. Bruno est conçu pour composer, organiser, envoyer et versionner des requêtes HTTP. Vous créez une collection, ajoutez des requêtes, les stockez dans des fichiers .bru, les exécutez, puis vous suivez le tout dans Git. Ce modèle est rapide, local-first et efficace lorsque vous explorez ou vérifiez une API existante.

Essayez Apidog aujourd’hui

Mais « orienté requêtes » et « orienté conception » ne répondent pas au même problème :

• Orienté requêtes : comment appeler ce endpoint ?
• Orienté conception : à quoi doit ressembler ce endpoint avant que le backend ne soit implémenté ?

C’est dans cet écart que les équipes API commencent souvent à perdre du temps : validations tardives, contrats implicites, documentation en retard, mocks bricolés et intégrations frontend bloquées.

Orienté requêtes vs orienté conception

Dimension	Orienté requêtes, comme Bruno	Orienté conception, natif OpenAPI
Artefact de départ	Une requête exécutable	Un contrat OpenAPI
Usage principal	Explorer et tester des API existantes	Concevoir des API avant le code
Source de vérité	Collection de requêtes	Spécification OpenAPI
Revue inter-équipes	Après l’existence des endpoints	Avant l’implémentation
Conception visuelle	Pas de couche dédiée par défaut	Concepteur visuel + éditeur de schémas
Risque de dérive	La collection peut ne plus refléter l’API réelle	Le contrat reste la référence
Git	Fort avec les fichiers .bru	Fort si la spécification est synchronisée avec Git

Aucune approche n’est intrinsèquement meilleure. Le bon choix dépend surtout de l’état de votre API : existe-t-elle déjà, ou devez-vous d’abord la définir comme contrat partagé ?

Comment fonctionne le modèle orienté requêtes de Bruno

Bruno stocke les requêtes dans des fichiers .bru en texte brut, dans un dossier que vous contrôlez. Il n’impose pas de compte cloud, de synchronisation propriétaire ou de télémétrie à désactiver. Pour les développeurs qui veulent traiter leur client API comme du code, c’est un vrai avantage.

C’est le cœur d’un workflow API natif Git : les requêtes vivent dans le dépôt, les diffs sont lisibles, et les changements peuvent passer par les mêmes pull requests que le code applicatif.

Un fichier .bru peut représenter une requête de façon simple et versionnable :

meta {
  name: Get user
  type: http
}

get {
  url: {{baseUrl}}/users/123
}

headers {
  Authorization: Bearer {{token}}
}

Bruno est particulièrement adapté pour :

• envoyer rapidement des requêtes contre une API existante ;
• vérifier les réponses pendant le développement ;
• organiser des collections locales ;
• écrire des scripts pré/post-requête ;
• ajouter des assertions ;
• versionner les requêtes dans Git.

Si votre travail consiste surtout à consommer, tester ou déboguer des API déjà disponibles, l’approche orientée requêtes est directe et productive. C’est aussi ce qui rend Bruno intéressant face à des plateformes plus larges, comme expliqué dans cette analyse des alternatives à Bruno.

Là où une collection de requêtes ne suffit plus

Le problème apparaît lorsque l’API n’existe pas encore, ou lorsque plusieurs équipes doivent s’accorder sur son comportement avant de coder.

1. Les requêtes décrivent des exemples, pas un contrat

Une collection de requêtes montre comment appeler un endpoint, mais elle ne définit pas forcément :

• tous les champs possibles d’un schéma ;
• les champs obligatoires ;
• les erreurs standardisées ;
• les codes de statut attendus ;
• les règles de validation ;
• les conventions de pagination ;
• les évolutions de version.

Par exemple, une requête peut montrer ceci :

{
  "id": "usr_123",
  "email": "[e-mail]"
}

Mais elle ne dit pas clairement si email est obligatoire, si id est généré côté serveur, ou si d’autres champs comme name, role ou createdAt existent.

Avec OpenAPI, le contrat devient explicite :

openapi: 3.1.0
info:
  title: Users API
  version: 1.0.0

paths:
  /users/{id}:
    get:
      summary: Récupérer un utilisateur
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Utilisateur trouvé
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "404":
          description: Utilisateur introuvable

components:
  schemas:
    User:
      type: object
      required:
        - id
        - email
      properties:
        id:
          type: string
        email:
          type: string
          format: email

Ici, le endpoint n’est pas seulement un exemple d’appel : c’est un contrat vérifiable.

2. La dérive entre API réelle et collection est facile

Quand la collection est la source de vérité, elle reflète seulement ce que quelqu’un a déjà testé. L’API réelle peut évoluer :

• un champ est ajouté ;
• un paramètre devient obligatoire ;
• une validation est renforcée ;
• une réponse d’erreur change ;
• un endpoint est déprécié.

La collection peut rester inchangée jusqu’à ce qu’un test casse ou qu’une équipe cliente découvre le problème.

Dans un workflow centré sur OpenAPI, la spécification devient la référence. L’implémentation, la documentation, les mocks et les tests peuvent être alignés sur ce contrat.

3. La revue de conception arrive trop tard

Relire un dossier de requêtes permet de comprendre comment une API est appelée aujourd’hui. Mais ce n’est pas le meilleur support pour approuver une conception avant l’implémentation.

Pour une revue API efficace, les équipes ont besoin de valider tôt :

• les noms de ressources ;
• les schémas ;
• les types ;
• les erreurs ;
• les conventions REST ;
• la compatibilité avec les clients ;
• les changements cassants.

Une spécification OpenAPI est plus adaptée à cette revue qu’une collection de requêtes.

Quand choisir une approche orientée conception

L’approche orientée conception devient utile dès que l’API est une interface partagée, pas seulement un service à tester.

Cas 1 : nouvelle API

Si l’API n’existe pas encore, commencez par le contrat.

Workflow recommandé :

1. Définir les ressources.
2. Décrire les endpoints.
3. Modéliser les schémas de requête et de réponse.
4. Standardiser les erreurs.
5. Générer des mocks.
6. Laisser le frontend intégrer le mock.
7. Implémenter le backend selon la spécification.
8. Vérifier que l’implémentation respecte le contrat.

Cela évite de reconstruire une spécification après coup à partir de requêtes déjà codées.

Cas 2 : plusieurs équipes dépendent de l’API

Si une équipe backend expose une API utilisée par une ou plusieurs équipes frontend, mobile ou partenaires, la spécification devient l’accord commun.

Un workflow plus robuste ressemble à ceci :

Design OpenAPI
      ↓
Revue du contrat
      ↓
Mock API
      ↓
Développement frontend et backend en parallèle
      ↓
Tests contre le contrat
      ↓
Publication de la documentation

Le frontend n’a pas besoin d’attendre que tous les endpoints réels soient prêts. Il peut travailler contre un mock validé par le contrat.

Cas 3 : API publique

Pour une API publique, la documentation et la stabilité font partie du produit. Une spécification maintenue permet de gérer plus proprement :

• la documentation de référence ;
• le versioning ;
• les changements cassants ;
• les SDK ou clients générés ;
• les contrats consommés par des développeurs externes.

Apidog : conception API + mode Spec-First

Apidog adopte une approche orientée conception tout en conservant un workflow compatible avec OpenAPI et Git.

Vous pouvez travailler de deux manières dans le même projet.

Option 1 : concepteur visuel

Utilisez l’interface pour définir :

• les endpoints ;
• les méthodes HTTP ;
• les paramètres ;
• les schémas de requête ;
• les schémas de réponse ;
• les composants réutilisables ;
• les exemples ;
• les statuts de réponse.

C’est pratique pour les équipes qui veulent concevoir l’API sans écrire directement du YAML.

Option 2 : mode Spec-First

Utilisez un éditeur de code pour modifier directement la spécification OpenAPI.

Cela convient aux développeurs qui préfèrent travailler dans un format explicite :

paths:
  /orders:
    post:
      summary: Créer une commande
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateOrderRequest"
      responses:
        "201":
          description: Commande créée

Le point important : le concepteur visuel et l’éditeur Spec-First restent synchronisés. Une personne peut travailler sur le contrat OpenAPI brut pendant qu’une autre ajuste la conception dans l’interface visuelle.

Synchronisation Git

Le mode Spec-First prend aussi en charge une synchronisation Git bidirectionnelle. La spécification peut vivre dans votre dépôt comme un fichier réel, passer par les pull requests, puis être relue comme le reste du code.

Cela applique le principe natif Git non plus seulement aux collections de requêtes, mais au contrat API lui-même.

La documentation complète du fonctionnement est disponible ici : documentation du mode Spec-First.

Pour approfondir la différence entre ces workflows, consultez aussi spec-first vs design-first dans Apidog.

Comment choisir selon la maturité de votre équipe

Voici une règle simple : choisissez l’outil selon le cycle de vie de votre API.

Vous consommez surtout des API existantes

Utilisez une approche orientée requêtes.

Elle est suffisante si vous avez besoin de :

• tester des endpoints ;
• déboguer des réponses ;
• organiser des collections ;
• lancer des assertions ;
• versionner vos requêtes.

Bruno est bien aligné avec ce cas d’usage.

Vous construisez une API utilisée par une autre équipe

Passez à une approche contractuelle.

Dès qu’une autre équipe dépend de vos endpoints, une collection de requêtes devient insuffisante comme source de vérité. Une spécification OpenAPI permet de valider la forme de l’API avant le code.

Vous maintenez des API publiques ou de nombreuses API internes

Adoptez une approche orientée conception.

À ce stade, la spécification sert à la fois de :

• contrat ;
• documentation ;
• base de génération ;
• support de gouvernance ;
• référence pour les tests ;
• point d’entrée pour les équipes consommatrices.

Résumé pratique

Utilisez Bruno si votre priorité est :

• appeler rapidement des endpoints ;
• tester des API existantes ;
• garder vos collections en local ;
• versionner des requêtes dans Git.

Utilisez une approche orientée conception si votre priorité est :

• définir une API avant l’implémentation ;
• aligner plusieurs équipes ;
• produire des mocks tôt ;
• générer une documentation fiable ;
• maintenir un contrat OpenAPI ;
• éviter la dérive entre documentation, tests et backend.

La différence n’est donc pas une question de préférence personnelle. Elle dépend du rôle de votre API : simple service à tester, ou contrat partagé à concevoir, valider et maintenir.

FAQ

Bruno est-il orienté requêtes ou orienté conception ?

Bruno est orienté requêtes. Son modèle principal consiste à composer, organiser et envoyer des requêtes stockées sous forme de fichiers texte brut. Il est donc très adapté à l’exploration et au test d’API existantes.

Peut-on faire du design-first dans Bruno ?

Pas nativement comme dans un outil centré sur OpenAPI. Bruno se concentre sur les requêtes plutôt que sur une spécification utilisée comme source de vérité. Pour définir, réviser et maintenir un contrat avant le code, un outil orienté conception est plus adapté.

Faut-il abandonner Git pour passer à l’approche orientée conception ?

Non. Le principe natif Git peut aussi s’appliquer à la spécification OpenAPI. Avec un workflow Spec-First, le contrat peut vivre dans votre dépôt, être relu dans des pull requests et rester synchronisé avec l’outil de conception.