MSD-08-COLL · Colecciones Postman e Insomnia

La primera llamada a la API no debería comenzar escribiendo una petición desde cero.

Toda la operación. Una sola plataforma.

---

Objetivo del capítulo

Definir las colecciones oficiales de Postman e Insomnia de Roustix, generadas automáticamente desde la especificación OpenAPI 3.1, permitiendo que cualquier desarrollador explore, pruebe y documente la API sin configuración manual.

Las colecciones representan una implementación práctica del contrato MAG v1.0, garantizando consistencia entre documentación, SDK y herramientas de prueba.

→ MSD-03 · OpenAPI · MSD-07 · Quick Start

---

1 · Filosofía

La documentación explica la API.

Las colecciones permiten ejecutarla.

OpenAPI
      │
      ▼
Colección oficial
      │
      ├── Postman
      │
      └── Insomnia
            │
            ▼
       API Roustix

Las colecciones nunca se editan manualmente de forma permanente — siempre se generan desde OpenAPI.

Regla	Descripción
OpenAPI primero	Cambio en MAG → OpenAPI → regenerar colecciones
Sin drift	No duplicar paths fuera del contrato
Sandbox	Variables apuntan a empresa-demo

---

2 · Objetivos

Las colecciones permiten:

• explorar todos los endpoints
• autenticarse mediante JWT
• probar recursos REST
• validar respuestas
• compartir ejemplos
• acelerar el desarrollo

Son una herramienta de aprendizaje y de pruebas.

---

3 · Colección Postman

Nombre oficial: Roustix API v1

Estructura:

Roustix API v1
│
├── Authentication
├── Me
├── Maintenance
│     ├── Assets
│     ├── Work Orders
│     ├── Schedules
│     └── Lubrication
│
├── Inventory
├── Purchases
├── Sales
├── CRM
└── Admin

Cada carpeta corresponde a un módulo definido en MAG-04.

Archivo: docs/api/collections/roustix-api-v1.postman_collection.json

Entorno Sandbox: roustix-sandbox.postman_environment.json

---

4 · Colección Insomnia

La organización replica exactamente la colección de Postman.

Roustix API v1
│
├── Authentication
├── Maintenance
├── Inventory
├── Admin
└── ...

El objetivo es que ambas herramientas ofrezcan la misma experiencia.

Archivo: docs/api/collections/roustix-api-v1.insomnia.json

---

5 · Variables de entorno

Las colecciones utilizan variables reutilizables:

Variable	Descripción
base_url	URL base del servidor (http://127.0.0.1:5000)
api_v1	{{base_url}}/api/v1
token	JWT activo
empresa_slug	Tenant Sandbox (empresa-demo)
asset_id	Activo de ejemplo
work_order_id	OT de ejemplo

Ejemplo:

{{api_v1}}/me
Authorization: Bearer {{token}}

No se almacenan credenciales reales dentro de las colecciones — solo placeholders.

Local hoy: algunos endpoints legacy usan /api/auth/login y /api/activos. La colección base incluye rutas v1; ver collections/README.md para importación local.

---

6 · Autenticación automática

La carpeta Authentication incluye el flujo completo:

POST /api/v1/auth/login

El JWT obtenido se almacena automáticamente como variable token (script Postman / Insomnia chain).

Login
   │
   ▼
 JWT
   │
   ▼
Variable token
   │
   ▼
Resto de endpoints

→ MAG-02 · JWT

---

7 · Generación

Las colecciones se generan automáticamente desde:

docs/api/openapi.v1.yaml

Proceso:

MAG
   │
   ▼
OpenAPI
   │
   ▼
Generador (OpenAPI Generator · openapi2postman · insomnia-importer)
   │
   ▼
Postman · Insomnia

No existen colecciones mantenidas manualmente en el flujo de release — la versión en repo es snapshot hasta CI automatizado (MSD v1.0).

Herramienta	Comando (planificado)
Postman	openapi2postmanv2 -s openapi.v1.yaml -o roustix-api-v1.postman_collection.json
Insomnia	Generación desde OpenAPI import en CI

---

8 · Casos de uso

Las colecciones permiten:

Caso	Audiencia
Probar nuevos endpoints	Desarrollo
Validar autenticación	Integradores
Demostrar funcionalidades	Comercial · MCM
Depurar integraciones	Soporte L2
Capacitación	Partners
Verificar cambios pre-release	QA API

También sirven como base para pruebas automatizadas (Newman · Insomnia CLI).

---

9 · Versionado

Las colecciones siguen el mismo ciclo de vida que la API (MAG-07):

Colección	API
Roustix API v1	MAG v1
Roustix API v2	MAG v2

Cada versión mantiene su propia colección independiente.

---

10 · Buenas prácticas

#	Regla
1	Generar las colecciones desde OpenAPI
2	No editar colecciones manualmente en release
3	Utilizar variables de entorno
4	No almacenar credenciales reales
5	Sincronizar cada publicación con MAG
6	Probar todas las solicitudes antes de cada versión

---

11 · Distribución

Las colecciones están disponibles desde:

Recurso	Ubicación
Developer Portal	Descarga directa (MSD-02)
Repositorio	docs/api/collections/
OpenAPI	Regeneración automática (CI)
Sandbox	Importación inmediata

Archivos:

Archivo	Formato
roustix-api-v1.postman_collection.json	Postman Collection v2.1
roustix-api-v1.insomnia.json	Insomnia Export v4
roustix-sandbox.postman_environment.json	Postman Environment

Importar en Postman: File → Import → seleccionar colección + entorno Sandbox.

---

Filosofía del capítulo

Las colecciones oficiales convierten el contrato de la API en una experiencia interactiva. En lugar de construir solicitudes manualmente, el desarrollador importa una colección, se autentica y comienza a trabajar en minutos.

MSD-08 establece las herramientas oficiales de exploración y prueba de Roustix, garantizando que documentación, OpenAPI y herramientas de desarrollo evolucionen siempre de forma sincronizada.

---