Pergaminos Rápidos: Bruno y tu API en el mismo repositorio

¿Te ha pasado que necesitas probar un endpoint y lo primero que tienes que hacer es registrarte en una plataforma, crear una cuenta, confirmar un correo y aceptar términos que nadie lee? A mí sí, y más de una vez.

Postman se fue llenando de funciones que nunca pedí y otras muy avanzadas que nunca utilizaré (esa IA que aparece en cada esquina me tiene harto), Insomnia me secuestró mis endpoints hasta que me registré, y al final la experiencia de "solo quiero hacer un GET" se transformó en un trámite burocrático.

Por esto decidí migrar a Bruno: un cliente de APIs open source, offline, sin cuentas, sin nube y sin IA molesta. Bruno almacena todo como archivos de texto plano en tu sistema de archivos, lo que abre una puerta muy interesante: tener la documentación de tus endpoints dentro del mismo repositorio de tu backend.

Eso es exactamente lo que vamos a hacer en este Pergamino.

Capítulo 1: La idea

Bruno permite guardar las colecciones donde quieras, y al ser archivos de texto plano, se pueden versionar con Git sin problemas. Yo decidí aprovechar esto con una convención propia: en cada proyecto backend, creao un directorio docs/api donde vive la colección de Bruno con todos los endpoints del proyecto.

De esta forma, a medida de que voy desarrollando endpoints y los voy probando con Bruno, esos endpoints quedan documentados y con seguimiento dentro del mismo repositorio, bajo el mismo control de versiones.

Esto te permite:

• Gestionar cada repositorio y sus endpoints de forma independiente.
• Si alguien clona mi backend, puede abrir docs/api con Bruno y probar todos los endpoints de inmediato.
• Cada cambio en los endpoints queda registrado en el historial de Git junto con el código que lo provocó.

Capítulo 2: Crear la colección en tu proyecto

2.1 Preparar el directorio

Primero, ve a la raíz de tu proyecto y solo crea este directorio (también puedes hacerlo manualmente):

$ mkdir docs

2.2 Crear la colección desde Bruno

Ahora abre Bruno y haz clic en "Create Collection". Te aparecerá inmediatamente la opción con el nombre del proyecto, ahí deberás hacer click en la tuerca a la derecha del nombre para abrir las opciones avanzadas:

• Name: el nombre de tu proyecto, por ejemplo: "Mi App"
• Location: selecciona la carpeta docs que acabas de crear en la raíz de tu proyecto.
• Folder Name: el nombre que tendrá el directorio donde se almacenarán tus endpoints. Por convención, yo utilizo api.

Bruno generará un archivo opencollection.yml dentro de docs/api con la configuración de la colección.

2.3 Resultado

Tu proyecto debería verse así:

.
├── Dockerfile
├── docs
│   └── api
│       └── opencollection.yml # Configuración de la colección
├── eslint.config.mjs
├── package.json
├── README.md
├── src
├── tsconfig.json
└── ...

A partir de aquí, cada vez que crees una request en Bruno, se generará un archivo .yml y un .gitignore dentro de docs/api. Estos archivos son YAML estándar: legibles, editables en cualquier editor y versionables con Git.

Capítulo 3: Abrir una colección existente

Si alguien clona tu repositorio y quiere probar los endpoints, solo necesita:

1. Abrir Bruno.
2. Hacer clic en "Open Collection".
3. Navegar hasta la carpeta docs/api del proyecto.
4. Seleccionarla.

Bruno leerá el opencollection.yml y cargará todas las requests automáticamente. Sin cuentas, sin importaciones, sin configuraciones.

Capítulo 4: Ambientes develop, staging y production

Aquí es donde la cosa se pone buena. Bruno permite crear variables de entorno dentro del directorio environments/ de tu colección. Cada ambiente se guarda como un archivo .yml que sí se commitea, lo que significa que todo el equipo tendrá acceso a las URLs de cada ambiente sin tener que pedírselas a nadie.

4.1 ¿Qué ambiente es cada uno?

Antes de crear los archivos, conviene definir qué representa cada ambiente. Al menos yo tengo esta convención:

• Develop: tu ambiente local de desarrollo. Es el localhost donde levantas tu backend mientras programas.
• Staging: el ambiente de staging. Es la rama develop desplegada en un servidor, donde se prueban los cambios antes de llegar a producción. Por lo general este ambiente existe en proyectos más grandes.
• Production: el ambiente de producción. Es la rama main desplegada, el que usan los usuarios reales.

4.2 Crear los ambientes desde Bruno

Para crear un ambiente, haz clic en el selector de entornos en la esquina superior derecha de Bruno (donde dice "No Environment") y selecciona "Collection" > "+ Create". Desde ahí puedes crear cada ambiente con sus variables.

Por ejemplo, para el ambiente Develop:

• Name: Develop
• Variables:
  • BASE_URL: localhost:3000

Repite el proceso para Staging y/o Production con sus respectivas URLs.

4.3 ¿Cómo se ve por dentro?

Bruno guardará cada ambiente como un archivo .yml dentro de environments/. Si abres estos archivos, verás algo así:

environments/Develop.yml

name: Develop
variables:
  - name: BASE_URL
    value: http://localhost:3000

environments/Production.yml

name: Production
variables:
  - name: BASE_URL
    value: http://api.miapp.com

4.4 Usar las variables de ambiente en tus requests

Una vez creados los ambientes, puedes referenciar sus variables usando la sintaxis {{variable}}. Por ejemplo, en la URL de una request:

{{BASE_URL}}/api/v1/users

Para cambiar de ambiente, simplemente selecciónalo desde el dropdown en la esquina superior derecha de Bruno. Si estás desarrollando en local, selecciona Develop. Si quieres probar contra producción, cambia a Production. Incluso puedes cambiar de colores los ambientes; siempre elijo el rojo como color para trabajar en entornos de producción.

Capítulo 5: Variables sensibles con .env

Ya tenemos las URLs de cada ambiente compartidas para todo el equipo. Ahora necesitamos un lugar seguro para las credenciales que cada desarrollador usa para autenticarse: emails, contraseñas, API keys, etc.

Para esto, Bruno soporta archivos .env al estilo de cualquier proyecto de Node.

5.1 Crear el archivo .env

Dentro de docs/api, crea un archivo .env:

$ touch docs/api/.env

En ese archivo, añade las variables sensibles que necesites:

[email protected]
PASSWORD=miPasswordSeguro123

5.2 Actualizar el .gitignore

Como dije anteriormente, Bruno genera automáticamente el archivo docs/api/.gitignore donde dentro tiene el .env* para que ningún .env ni derivados tengan seguimiento.

EMAIL=
PASSWORD=

Por defecto, el .gitignore de Bruno bloquea todos los archivos que empiecen con .env, incluyendo tu .env.example. Para que sí se commitee, te enseño este truco: edita el .gitignore y añade !.env.example."

5.3 Usar las variables en Bruno

Las variables del .env se pueden referenciar con la sintaxis {{process.env.VARIABLE}}.

Esto mantiene una separación clara: las URLs viven en environments/ (compartidas en Git) y las credenciales viven en .env (privadas para cada desarrollador).

Capítulo 6: Automatizar el token de sesión

Este es el truco que te va a ahorrar la mayor cantidad de tiempo: hacer login una vez y que el token quede disponible automáticamente para el resto de las requests.

6.1 Crear la request de Login

En Bruno, crea una nueva request llamada Login (o Auth Login, como prefieras). Configúrala así:

• Method: POST
• URL: {{BASE_URL}}/auth/login
• Body (JSON):

{
  "email": "{{process.env.EMAIL}}",
  "password": "{{process.env.PASSWORD}}"
}

6.2 Almacenar el token automáticamente

En la pestaña "Script" de la request de Login, ve a la sección de Post Response y añade el siguiente script:

bru.setVar("TOKEN", res.body.token);

Este script toma el token de la respuesta y lo guarda como una variable de runtime que estará disponible mientras Bruno esté abierto.

6.3 Usar el token en las demás requests

Ahora, en cualquier otra request que requiera autenticación, ve a la pestaña "Auth" y selecciona Bearer Token. En el campo del token, escribe:

{{TOKEN}}

De esta forma, cada vez que hagas login, el token se almacena automáticamente y todas las demás requests lo usarán sin que tengas que copiar y pegar nada.

6.4 Resultado final

Tu estructura debería verse así:

docs/
└── api/
    ├── opencollection.yml
    ├── .env                  # Credenciales sensibles (en .gitignore)
    ├── .env.example          # Plantilla para el equipo (commiteado)
    ├── environments/
    │   ├── Develop.yml       # http://localhost:3000
    │   └── Production.yml    # https://api.miapp.com
    ├── auth/
    │   └── login.yml         # Request de login con post-script
    ├── users/
    │   ├── get-users.yml
    │   └── create-user.yml
    └── products/
        ├── get-products.yml
        └── create-product.yml

Capítulo 7: Despedida

Con esto ya tienes un flujo completo: tu backend y la documentación de sus endpoints viviendo juntos en el mismo repositorio, con ambientes compartidos en environments/ para cambiar entre dev, stg y prd con un click, credenciales seguras en el .env y un sistema de autenticación automática que te ahorra copiar tokens a mano.

Quien clone tu proyecto solo necesita Bruno instalado, un .env con sus credenciales y ya puede probar todo. Las URLs de cada ambiente ya estarán ahí esperándolo. Sin registros, sin nubes, sin fricciones.

Recuerda que el post que acabo de escribir solo muestra las convenciones que yo utilizo para trabajar, pero puedes crear las tuyas; además, Bruno está lleno de herramientas, te invito a leer la documentación oficial e ir aprendiendo más funcionalidades. ¿Y tú, también estás aburrido de registrarte para poder probar tus endpoints? Te leo en los comentarios.

Referencias:

Bruno - The Git-Native API Client

Bruno is the Git-native API client for REST, GraphQL, gRPC and Websocket. A local and open-source solution to Postman. Fast, developer-first, and no cloud syncing.

Bruno Software Inc.Bruno Software Inc.