Hace poco, Postman introdujo el control de versiones de Git para tu trabajo. Esto te facilita mucho la vida a la hora de realizar un seguimiento de tus cambios.
Junto con el control de versiones de Git, también han añadido una opción de IA para realizar un seguimiento de tus cambios en la API y actualizar automáticamente las solicitudes dentro de Postman. Por supuesto, esto requiere una suscripción de pago.
Una solución alternativa es utilizar tu suscripción a IA existente, como Copilot, Claude u otras. Veamos cómo hacerlo.
Crear un entorno Git en Postman
En primer lugar, debemos crear un entorno Git en Postman. Selecciona Crear → Desde repositorio Git y elige la carpeta que contiene tu código.
Esto creará dos carpetas:
.postman
postman
Aquí es donde se almacenarán todas tus solicitudes y claves.
NOTA: Ten en cuenta que los archivos de entorno probablemente contengan secretos. Añádelos a .gitignore si es necesario.
Definir instrucciones de Postman
En primer lugar, define las instrucciones para crear cada elemento. Puedes obtener el archivo completo en:
Repasemos la estructura del archivo:
- Descripción de la carpeta: Dentro de la carpeta «postman», define qué tipo de información se incluye en cada subcarpeta.
Por ejemplo, los entornos se almacenan como archivos YAML dentro de /environments.
- Descripción de los elementos: Una vez que sepa dónde va cada archivo, defina los pasos para crearlos.
Usando el ejemplo de los entornos: para crear un archivo YAML, necesita un nombre y unas claves. Las claves se explican por sí mismas en su mayoría, pero puede añadir detalles para cada línea si es necesario.
Ejemplo:
name: PRO
values:
- key: base_url
value: «https://api.example.com»
enabled: true
Añade cualquier instrucción adicional: uso de la clave, errores, etc.
Configurar las instrucciones principales
Una forma de utilizarlo es crear un agente o una configuración en las instrucciones principales de Copilot. Cada vez que el agente realice un cambio en un controlador, deberá realizar los cambios correspondientes en Postman:
Un ejemplo que puede utilizar es:
Siempre que se añada, modifique o elimine un controlador, la colección de Postman debe actualizarse para reflejar ese cambio.
Utiliza el archivo `postman/instructions.md` como guía para leer, editar y crear colecciones, carpetas, solicitudes y archivos de entorno de Postman.
Si una solicitud requiere claves secretas o valores específicos del entorno, recórrelos de la carpeta `.deploy` y haz referencia a ellos mediante variables de entorno siempre que sea posible.
Cada solicitud debe incluir al menos una validación mínima utilizando scripts de Postman. Como mínimo, añade una validación básica de la respuesta, como una comprobación del código de estado.
En esencia, debes especificar dónde obtener la información sobre cómo hacerlo y qué quieres que haga tu agente; básicamente, eso significa qué hacer y cómo hacerlo.
Otro caso de uso
Con las instrucciones de Postman disponibles, puedes utilizarlas en cualquier momento sin crear un agente específico; en mi caso, quiero poder activar el proceso de vez en cuando.
Para ello, solo tengo que añadir esto a mi solicitud cuando lo necesito:
Utiliza `postman/instructions.md` como instrucciones para leer, editar y crear colecciones, carpetas, solicitudes y archivos de entorno de Postman.
....
Aquí describo lo que quiero hacer.
Conclusión
Aunque estoy familiarizado con otras herramientas del mercado, me gusta especialmente Postman, y estas instrucciones para Copilot, aunque son sencillas, me ayudan a mantener mis proyectos al día sin perder tiempo en estas tareas repetitivas.
Sobre todo, me ha ayudado a crear una colección de Postman donde antes no tenía ninguna, o donde las que ya tenía estaban muy desactualizadas
Esta es una forma sencilla de crear y modificar tus colecciones de Postman con Copilot. Si quieres explorar otros métodos, te recomiendo que leas sobre cómo sincronizar colecciones de Postman a través de OpenAPI
Guía de Postman:
Aquí tienes toda la información sobre la estructura Git de Postman
Estructura del repositorio
postman/
collections/
<NombreDeColección>/
.resources/
definition.yaml # Definición de la colección
<NombreDeCarpeta>/
.resources/
definition.yaml # Definición de la carpeta
<NombreDeSolicitud>.request.yaml
<NombreDeSolicitud>.request.yaml
environments/
<NombreDeEntorno>.environment.yaml
Definiciones de componentes
Colección y carpeta
Las colecciones y las carpetas tienen el mismo tipo. Ubicación: postman/collections/<NombreDeColección>/.resources/definition.yaml Ubicación: postman/collections/<NombreDeColección>/<NombreDeCarpeta>/.resources/definition.yaml
$kind: collection
name: <NombreDeColección>
Solicitud
Ubicación: <NombreDeLaSolicitud>.request.yaml (dentro de una colección o carpeta)
Estructura mínima:
$kind: http-request
name: <NombreDeLaSolicitud>
url: «[base_url]/path»
method: GET|POST|PUT|DELETE|PATCH
Ejemplo completo:
$kind: http-request
name: Obtener artículos
url: «[base_url]/api/v1/articles»
method: GET
headers:
x-api-key: «[api_key]»
Content-Type: application/json
queryParams:
customerId: «[customerId]»
page: «1»
body:
type: json
content: |+
{
«orderNumber»: «ORDER-123»
}
scripts:
- type: afterResponse
code: | -
pm.test(«El código de estado es 200», function () {
pm.response.to.have.status(200);
});
language: text/javascript
order: 2000
Referencia de campos de solicitud
Obligatorios
$kind: http-request
name: Nombre de la solicitud
url: URL de la solicitud
method: Método HTTP
Opcional
headers: Formato de mapa o lista
queryParams: Parámetros de la cadena de consulta
body: Cuerpo de la solicitud (json, formdata, raw, etc.)
auth: Definición de autorización
scripts: Scripts previos a la solicitud o posteriores a la respuesta
order: Valor de ordenación de la interfaz de usuario
Formatos de encabezados
Formato de mapa:
headers:
x-api-key: «[api_key]»
Content-Type: application/json
Formato de lista:
headers:
- key: Accept
value: application/json
enabled: true
Tipos de cuerpo
JSON:
cuerpo:
tipo: json
contenido: |+
{
«campo»: «valor»
}
Datos de formulario:
cuerpo:
tipo: formdata
contenido:
- clave: campo1
valor: valor1
- clave: archivo
tipo: archivo
src: ./ruta/al/archivo.txt
Variables de entorno
Las variables utilizan la sintaxis [nombre_variable]. Deben definirse en postman/environments/<EnvName>.environment.yaml:
No utilices en <EnvName> la palabra DEV.
nombre: PRO
valores:
- clave: base_url
valor: «https://api.example.com»
habilitado: true
- clave: api_key
valor: «secret_key_value»
habilitado: true
- clave: customerId
valor: «12345»
habilitado: true
Reglas fundamentales
Utiliza siempre [nombre_de_variable] para:
URL base
Claves API
Valores específicos del entorno
Valores reutilizables
Nunca codifiques de forma estática:
Secretos o credenciales
URL específicas del entorno
ID de cliente o datos similares
Requisitos de YAML:
Sintaxis YAML válida
Sangría correcta (2 espacios)
Citas de cadenas adecuadas para URL y valores
Requisitos de estructura:
Cada colección debe tener .resources/definition.yaml
Cada carpeta debe tener .resources/definition.yaml
Los nombres de los archivos de solicitud deben terminar en .request.yaml
Validación de variables:
Verifica que todas las [variables] existan en los archivos de entorno
Comprueba que los nombres de las variables coincidan exactamente (distingue entre mayúsculas y minúsculas)
Instrucciones de edición
Editar el nombre de la colección: Modifica el nombre en el archivo .resources/definition.yaml de la colección
Editar el nombre de la carpeta: Modifica el nombre en el archivo .resources/definition.yaml de la carpeta
Editar la solicitud: Modifica directamente el archivo .request.yaml
Añadir/eliminar campos: Actualiza el YAML manteniendo la estructura adecuada
Cambiar variables de entorno: Edita los archivos en postman/environments/
Buenas prácticas y errores comunes
Todas las variables deben declararse
Problema: Utilizar [nombreDeVariable] en URL o parámetros sin declararlas en el archivo de entorno.
Lista de comprobación para nuevas colecciones
Al crear o actualizar colecciones de Postman:
[ ] Entornos: Crea archivos de entorno para TODOS los entornos de implementación
[ ] Variables: Declara TODAS las variables utilizadas en las URL, los encabezados y los cuerpos
[ ] Coherencia: Utiliza los mismos nombres de variables en todas las solicitudes
[ ] Pruebas: Añade una validación mínima del código de estado a cada solicitud y, si es posible, una validación del modelo
[ ] Validación de modelos: Añada pruebas de estructura de respuesta para los puntos finales GET
[ ] Autenticación: Incluya los encabezados requeridos (por ejemplo, X-Api-Key, Authorization) para todos los puntos finales protegidos
[ ] Cuerpos de ejemplo: Proporcione cuerpos JSON de ejemplo realistas para las solicitudes POST/PUT
[ ] Documentación: Añada comentarios en los cuerpos de solicitud complejos explicando la finalidad de los campos