¿Bruno es Request-First? Cuándo Necesitas una Herramienta Design-First

¿Es Bruno request-first? Sí. Bruno está diseñado para componer, organizar y enviar solicitudes HTTP: creas una colección, añades requests, las guardas en archivos .bru, las ejecutas y versionas todo en Git. Ese modelo funciona muy bien cuando necesitas explorar o probar una API que ya existe.

Prueba Apidog hoy

Pero request-first y design-first resuelven problemas distintos. Request-first pregunta: ¿cómo llamo a este endpoint? Design-first pregunta: ¿cómo debería ser este endpoint antes de implementarlo? Esa diferencia importa cuando varias personas o equipos necesitan acordar un contrato de API antes de escribir código.

En este artículo veremos cuándo Bruno encaja bien, dónde aparece la fricción de un flujo request-first y cómo un flujo design-first basado en OpenAPI ayuda a diseñar APIs nuevas o compartidas.

Request-first vs design-first: comparación rápida

Dimensión	Request-first (Bruno)	Design-first (nativo de OpenAPI)
Artefacto inicial	Una solicitud ejecutable	Un contrato OpenAPI
Mejor para	Explorar y probar APIs existentes	Diseñar APIs nuevas o compartidas antes del código
Fuente de verdad	Colección de solicitudes	Especificación OpenAPI
Revisión entre equipos	Después de que los endpoints existen	Antes de implementar el servidor
Diseño visual	No incluido por defecto	Diseñador visual y editor de esquemas
Riesgo de desviación	La colección puede quedarse atrás respecto a la API real	La especificación actúa como contrato principal
Git	Fuerte con archivos .bru	Fuerte cuando la especificación se sincroniza con Git

La elección depende del estado de tu API:

• Si la API ya existe, request-first suele ser suficiente.
• Si la API se está diseñando o será consumida por otros equipos, design-first reduce errores de integración.

Cómo funciona el modelo request-first de Bruno

Bruno guarda las solicitudes como archivos .bru de texto plano dentro de una carpeta que puedes versionar. No requiere una cuenta en la nube obligatoria ni sincronización propietaria. Para equipos que quieren que el cliente API se comporte como parte del repositorio, esto encaja bien con un flujo de trabajo API Git-native.

Bruno es útil cuando necesitas:

1. Explorar una API existente
   
   Apuntas a un servicio en ejecución, envías requests, inspeccionas respuestas y ajustas parámetros.

2. Versionar requests junto al código
   
   Los archivos .bru se revisan en PRs, se comparan con diffs legibles y se almacenan en Git.

3. Probar flujos comunes
   
   Puedes usar variables de entorno, scripts pre-request, scripts post-request y aserciones.

4. Evitar dependencia de un backend propietario
   
   Tus colecciones viven como archivos locales.

Un flujo típico con Bruno se ve así:

repo/
  api-requests/
    users/
      get-user.bru
      create-user.bru
  src/
  README.md

Esto funciona bien si tu objetivo es consumir o verificar endpoints existentes. También lo analizamos en esta comparación de alternativas a Bruno.

El coste de no tener una capa de contrato

La fricción aparece cuando la API todavía no existe o cuando varios equipos deben acordar su diseño.

1. Diseñar con ejemplos no impone estructura

En un flujo request-first, normalmente empiezas con una solicitud concreta:

POST /users
Content-Type: application/json

{
  "name": "Ana",
  "email": "[e-mail]"
}

Ese ejemplo ayuda a probar, pero no define por completo el contrato:

• ¿email es obligatorio?
• ¿Qué formato debe tener?
• ¿Qué errores devuelve el endpoint?
• ¿La respuesta incluye id, createdAt o ambos?
• ¿Qué ocurre si el usuario ya existe?

Un contrato OpenAPI permite expresar esas reglas de forma explícita:

paths:
  /users:
    post:
      summary: Crear usuario
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: Usuario creado
        '409':
          description: El usuario ya existe

2. La colección puede desviarse de la API real

Si la colección es la fuente de verdad, solo refleja lo que alguien probó. La implementación puede cambiar y la colección no enterarse hasta que una prueba falle.

Ejemplos comunes:

• Se añade un campo obligatorio.
• Se elimina un parámetro.
• Cambia el formato de error.
• Se endurece la validación.
• La documentación queda desactualizada.

En un flujo centrado en OpenAPI, el contrato va primero. La implementación, los mocks, la documentación y las pruebas se alinean contra esa especificación.

3. La revisión previa al código es más difícil

Revisar una carpeta de solicitudes ayuda a entender cómo se llama una API, pero no siempre muestra el diseño completo.

Para una revisión de diseño, normalmente necesitas validar:

• Nombres de recursos.
• Métodos HTTP.
• Códigos de estado.
• Esquemas de request y response.
• Errores estándar.
• Versionado.
• Compatibilidad hacia atrás.

Eso es más fácil cuando el artefacto revisado es una especificación OpenAPI, no una colección de ejemplos.

Cuándo gana design-first

Design-first es especialmente útil cuando la API es un contrato compartido.

1. APIs greenfield

Si todavía no existe implementación, empieza por la especificación:

openapi: 3.1.0
info:
  title: Users API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Listar usuarios
      responses:
        '200':
          description: Lista de usuarios

A partir de ese contrato puedes generar o mantener:

• Mocks.
• Documentación.
• Stubs de servidor.
• SDKs.
• Casos de prueba.
• Reglas de revisión.

2. Contratos entre varios equipos

Cuando backend y frontend trabajan en paralelo, OpenAPI permite acordar el contrato antes de que exista el endpoint real.

Flujo práctico:

1. Backend y frontend revisan la especificación.
2. Se aprueba el contrato en un PR.
3. Frontend consume un mock basado en OpenAPI.
4. Backend implementa contra la misma especificación.
5. Las pruebas validan que la implementación respeta el contrato.

Esto reduce bloqueos entre equipos.

3. APIs públicas

Si desarrolladores externos dependen de tu API, la especificación se convierte en parte del producto.

Un contrato mantenido ayuda a:

• Generar documentación consistente.
• Comunicar cambios breaking.
• Mantener versionado.
• Evitar ambigüedades.
• Facilitar onboarding.

La regla práctica: design-first gana cuando necesitas acuerdo antes del código, no solo pruebas después de desplegar.

Apidog design-first y Modo Spec-First

Apidog está construido alrededor de un flujo design-first. La idea es mantener OpenAPI como fuente de verdad sin perder una experiencia compatible con Git.

En un proyecto puedes trabajar de dos formas:

Opción 1: Diseñador visual

Útil cuando quieres definir la API sin escribir YAML manualmente.

Puedes modelar:

• Endpoints.
• Métodos HTTP.
• Parámetros.
• Headers.
• Bodies.
• Responses.
• Esquemas reutilizables.
• Componentes compartidos.

Opción 2: Modo Spec-First

Útil cuando quieres editar OpenAPI directamente como código.

Ejemplo:

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

El punto importante es que ambos modos se mantienen sincronizados. Un backend puede editar la especificación directamente mientras otra persona usa el diseñador visual, trabajando sobre el mismo contrato.

El Modo Spec-First también soporta sincronización bidireccional con Git: la especificación reside en tu repositorio, los cambios fluyen en ambas direcciones y el diseño de la API se revisa mediante PRs. Esa lógica Git-native se aplica al contrato OpenAPI, no solo a una colección de requests. Puedes ver los detalles en la documentación del Modo Spec-First.

El flujo resultante cubre ambas necesidades:

1. Diseñas el contrato primero.
2. Lo revisas en Git.
3. Generas mocks o documentación.
4. Implementas contra la especificación.
5. Pruebas los endpoints cuando están activos.

Para profundizar en estos modelos, consulta spec-first vs design-first en Apidog.

Cómo elegir según la madurez del equipo

Usa el estado de tu API como criterio principal.

Usa request-first si:

• Consumes APIs de terceros.
• Pruebas servicios ya desplegados.
• Trabajas solo o en un equipo pequeño.
• No necesitas un contrato formal.
• Quieres versionar requests simples en Git.

Usa design-first si:

• Estás creando una API desde cero.
• Hay varios equipos consumidores.
• Frontend y backend trabajan en paralelo.
• Necesitas documentación estable.
• Tienes APIs públicas o muchas APIs internas.
• Quieres revisar cambios de contrato antes de implementar.

Punto de transición

El cambio suele aparecer cuando una segunda persona o equipo depende de tus endpoints.

Mientras la API es interna y pequeña, una colección request-first puede bastar. Cuando la API se convierte en contrato compartido, OpenAPI empieza a ahorrar tiempo en revisión, integración y mantenimiento.

Preguntas frecuentes

¿Bruno es request-first o design-first?

Bruno es request-first. Su modelo central consiste en componer, organizar y enviar solicitudes almacenadas como archivos de texto plano. Es una buena opción para explorar y probar APIs existentes, pero no está centrado en crear un contrato OpenAPI antes de implementar la API.

¿Puedo hacer trabajo design-first en Bruno?

No de forma nativa como en una herramienta centrada en especificaciones. Bruno trabaja principalmente con solicitudes, no con un diseñador visual ni con un documento OpenAPI como fuente de verdad. Si necesitas definir y revisar un contrato antes del código, una herramienta design-first y nativa de OpenAPI encaja mejor.

¿Tengo que renunciar a Git para adoptar design-first?

No. La compatibilidad con Git también puede aplicarse a la especificación. Con el Modo Spec-First de Apidog, el documento OpenAPI puede vivir en tu repositorio y sincronizarse en ambas direcciones, de modo que el diseño de API se revisa igual que el código.