Creación de un servidor simulado Postman

Esta guía explica cómo utilizar los archivos de ejemplo de Postman proporcionados para crear un entorno de API simulado. Simulará los mismos puntos finales que se muestran en toda la documentación, sin necesidad de un back-end en vivo.

---

Requisitos previos

• Postman (versión de escritorio o web)

• Tres archivos JSON incluidos en este proyecto:

  • DataPipeline-Environment.json: define variables reutilizables como base_url, mock_base_url, api_token y stream_id.
  • DataPipeline-postman-collection.json: simula la API de ingesta de streaming de la documentación para pruebas reales o simuladas.
  • DataPipeline-MockServer-Collection.json: configura respuestas simuladas para los mismos puntos finales utilizando un servidor simulado de Postman.

Descargue los tres aquí: Descargar archivos de Postman

---

1. Importe los archivos a Postman

1. Abra Postman y haga clic en Importar.

2. Seleccione los archivos JSON descargados:

   • Las dos colecciones (DataPipeline-postman-collection.json y DataPipeline-MockServer-Collection.json).
   • El entorno (DataPipeline-Environment.json).

3. En el menú superior derecho del entorno, seleccione Entorno de canalización de datos (Data Pipeline Environment).

Ahora debería ver:

• Documentación de la canalización de datos Proyecto
• Canalización de datos - Colección de servidores simulados
• Entorno de canalización de datos

---

2. Crear el servidor simulado

1. Vaya a Servidores simulados (Mock Servers) en Postman.
2. Haga clic en Crear servidor simulado (Create Mock Server).
3. Elija Colección de servidores simulados de canalización de datos (Data Pipeline—Mock Server Collection).
4. Mantenga la configuración predeterminada y haga clic en Crear servidor simulado.

Postman generará una dirección de servidor simulado única, por ejemplo:

https://a12b34cd-1234-5678.mock.pstmn.io

---

3. Actualizar la variable de entorno

1. Vaya a Entornos → Entorno de canalización de datos (Environments → Data Pipeline Environment).
2. Busque la variable mock_base_url.
3. Reemplace el valor del marcador de posición:

# antiguo
https://mock-server-url-from-postman.io

# nuevo
https://a12b34cd-1234-5678.mock.pstmn.io

4. Guarde el entorno.

---

4. Envíe su primera solicitud simulada

1. Abra POST /v1/streams/ingest dentro de la Colección de servidores simulados.
2. Confirme que el entorno está activo.
3. Haga clic en Enviar (Send).

Debería ver una respuesta simulada 200 OK:

{
  "status": "accepted",
  "ingested_bytes": 204,
  "stream_id": "demo-stream-001",
  "message": "Evento recibido correctamente por el servidor simulado."
}

---

5. Pruebe una respuesta de error

Elimine un encabezado obligatorio o edite el cuerpo JSON para activar una respuesta 400 Solicitud incorrecta (Bad Request).

{
  "error": "invalid_format",
  "detail": "Falta el campo «timestamp» o no es válido. Se espera el formato ISO 8601."
}

---

6. Cambie entre pruebas en vivo y simuladas

• Para probar ejemplos «en vivo», utilice DataPipeline-postman-collection.json con {{base_url}}.
• Para probar localmente o sin conexión, utilice DataPipeline-MockServer-Collection.json con {{mock_base_url}}.
• Ambos se basan en el mismo DataPipeline-Environment.json para la gestión de variables.

Esto le permite probar tanto los ejemplos de la documentación como la API simulada sin cambiar las URL manualmente.

---

Visualización del flujo de solicitudes

• Mermaid (código)
• Mermaid (imagen)
• ASCII

sequenceDiagram
    participant Dev as Postman (usuario)
    participant Mock as Postman Mock Server
    participant Resp as Mock Response

    Dev->>Mock: POST /v1/streams/ingest
    Note right of Dev: Headers: Authorization, X-Stream-Id, Content-Type
    Mock-->>Resp: Simular una respuesta JSON 200 o 400
    Resp-->>Dev: Devolver la respuesta al cliente Postman

---

Por qué es importante

El uso de servidores simulados y colecciones de Postman le permite:

• Seguir los tutoriales y los ejemplos de API tal y como están escritos.
• Validar los formatos de solicitud y respuesta antes de la implementación.
• Probar entornos reales y simulados con una única configuración.
• Desarrollar y verificar la documentación junto con el diseño de la API.

---