Tutorial: Probar tu API con Postman

1. Objetivos de aprendizaje

Al terminar este tutorial vas a ser capaz de:

• Crear y enviar una petición HTTP desde Postman.
• Leer el código de estado, los headers y el body de una respuesta.
• Guardar una petición en una Collection para no reescribirla cada vez.
• Guardar la URL de tu backend en una variable de entorno, para no depender de dónde esté desplegado.
• Escribir un test simple que verifique el código de estado de la respuesta.
• Crear una petición POST con un body JSON y verificar que el backend responda 201 Created.
• Exportar tu Collection y tu Environment, y guardarlos en tu repositorio, versionados junto con tu código.

Prerrequisitos: tener Postman instalado (lo hiciste en el taller de ambiente de desarrollo), y tu backend corriendo con GET /artistas respondiendo (./mvnw spring-boot:run, como en el Paso 7 del tutorial de API REST) y con POST /artistas respondiendo, como quedó en el tutorial de agregar el endpoint POST.

---

2. Por qué probar con Postman

Ya verificaste tu endpoint con curl en el tutorial anterior. Eso sirve para una comprobación rápida, pero tiene un límite: cada vez que quieres repetirla tienes que volver a escribir el comando completo, y la respuesta llega como texto plano sin formato.

Postman resuelve las dos cosas: guarda la petición para reutilizarla con un clic, y te muestra la respuesta organizada (status, headers y body por separado, con el JSON formateado y coloreado).

Consejo

Vas a empezar con un GET sin body, la petición más simple posible. Más adelante en este mismo tutorial vas a probar un POST con un body JSON, y en el curso vas a seguir usando la misma herramienta para automatizar pruebas con scripts. Vale la pena que le agarres práctica desde lo simple.

---

3. Conceptos: Workspace, Collection, Request, variables y Environment

Antes de crear nada, vale la pena tener claro el vocabulario que vas a usar en el resto del tutorial (y en el resto del curso):

• Workspace: el espacio de trabajo donde vive todo lo demás. Por defecto tienes uno personal, llamado My Workspace; ahí van a quedar guardadas tus Collections y tus Environments mientras trabajas en el proyecto de forma individual.
• Request: una petición HTTP guardada, con su método (GET, POST, etc.), su URL, sus headers, su body y, opcionalmente, sus tests. Es la unidad más pequeña con la que trabajas en Postman.
• Collection: una carpeta que agrupa Requests relacionados, para que no queden sueltos ni se pierdan entre los de tus compañeros de curso. Vas a tener una Collection por módulo.
• Variable: un valor con nombre que reutilizas en varias Requests escribiendo {{nombreVariable}} en vez de escribir el valor literal en cada una.
• Environment: un conjunto de variables agrupadas con un propósito específico, por ejemplo “correr contra mi backend local”. Cambiar de Environment cambia de un solo golpe el valor de todas sus variables, sin tocar ninguna Request.

En los siguientes pasos vas a crear una Collection con dos Requests (GET y POST), un Environment con una variable para la URL base, y al final vas a exportar la Collection para dejarla versionada en tu repositorio.

---

4. Crear una Collection

1. Abre Postman y haz clic en New → Collection.
2. Nómbrala igual que tu módulo, por ejemplo Musical - Artistas.
3. Déjala creada: ahí vas a ir guardando las peticiones de tu módulo a medida que avances en el curso.

---

5. Crear un Environment para la URL base

Hoy tu backend corre en http://localhost:8080, pero eso va a cambiar: en algún momento del curso lo vas a desplegar en un servidor, y la URL va a ser otra. Si escribes esa URL directamente en cada petición, tienes que editarlas todas a mano cada vez que cambie. Guardarla en una variable de tu Environment te permite cambiarla en un solo lugar y que se actualicen todas tus peticiones.

1. En la esquina superior derecha, abre el selector de Environments (dice No Environment) → Add.
2. Nómbralo igual que tu proyecto, por ejemplo Musical - Local.
3. Agrega una variable:
   • Variable: baseUrl
   • Initial value y Current value: http://localhost:8080
4. Guarda, y selecciona ese Environment en el mismo selector de la esquina superior derecha (ya no debe decir “No Environment”).

Consejo

Cuando despliegues tu backend más adelante en el curso, solo vas a cambiar el Current value de baseUrl en el Environment, no cada petición de la Collection.

---

6. Crear la petición GET /artistas

Dentro de la Collection que acabas de crear:

1. Haz clic derecho sobre la Collection → Add request.
2. Nómbrala GET artistas.
3. Verifica que el método, a la izquierda de la barra de URL, esté en GET.
4. En la barra de URL, escribe:

{{baseUrl}}/artistas

5. Haz clic en Send.

Precaución

Si la URL se ve en rojo en vez de en naranja, Postman no está resolviendo {{baseUrl}}: revisa que hayas seleccionado el Environment del paso anterior en la esquina superior derecha.

Precaución

Si Postman responde con un error de conexión, tu backend no está corriendo. Vuelve al Paso 7 del tutorial de API REST y arráncalo con ./mvnw spring-boot:run antes de seguir.

---

7. Leer la respuesta

Debajo de la barra de URL, Postman te muestra tres cosas:

• El código de estado, junto al tiempo de respuesta: debería ser 200 OK.
• Headers, la pestaña con los headers de la respuesta, entre ellos Content-Type: application/json.
• Body, con el JSON completo, formateado e indentado.

Compara el body contra los datos de tu Gist: mismo número de artistas, mismos nombres, misma estructura anidada de álbumes y canciones.

Consejo

Si el body llega vacío ([]) en vez de tus artistas, no es un problema de Postman: revisa src/main/resources/datos.json en tu backend, tal como lo dejaste en el tutorial de la implementación en memoria.

---

8. Escribir un test que verifique el status code

Revisar el status a simple vista funciona, pero no queda registrado en ningún lado: si vuelves a correr la petición mañana, tienes que revisarlo de nuevo a mano. Un test lo deja verificado y visible en Test Results cada vez que envías la petición.

En la petición GET artistas, abre la pestaña Scripts (al lado de Body), elige Post-response y pega (en versiones anteriores de Postman, esta pestaña se llamaba Tests):

pm.test("Status code es 200 OK", () => pm.expect(pm.response.code).to.equal(200));

Haz clic en Send de nuevo. Debajo de la respuesta aparece la pestaña Test Results, con un ✅ junto al nombre de tu test.

Consejo

Es la misma sintaxis pm.test() / pm.expect() que vas a estudiar a fondo en Pruebas de API con Postman, donde vas a encadenar peticiones y probar POST, PUT y DELETE.

Precaución

Si el test falla, revisa primero lo básico antes de sospechar del test: ¿tu backend sigue corriendo? ¿seleccionaste el Environment del paso 5? Un error de conexión o una URL sin resolver hacen que el status nunca sea 200.

---

9. Crear la petición POST /artistas y verificar el 201

Un GET no manda datos, un POST sí: hay que decirle a Postman qué JSON enviar, en el body de la petición.

1. Haz clic derecho sobre la Collection → Add request.
2. Nómbrala POST artistas.
3. Cambia el método, a la izquierda de la barra de URL, a POST.
4. En la barra de URL, escribe lo mismo de siempre:

{{baseUrl}}/artistas

5. Abre la pestaña Body, selecciona raw, y a la derecha cambia el formato de Text a JSON.
6. Pega un artista nuevo, sin id y sin albumes (esos los asigna o los completa el backend):

{
  "nombre": "Shakira",
  "fotoArtistaUrl": "https://picsum.photos/seed/shakira/200",
  "paisOrigen": "Colombia",
  "fechaNacimiento": "1977-02-02",
  "biografia": "Cantante colombiana."
}

7. Haz clic en Send.

Precaución

Si el body no está en formato JSON (paso 5), Postman lo manda como texto plano y tu backend probablemente responda con un error, no con 201.

El status de una creación exitosa no es 200, es 201 Created. Abre la pestaña Scripts, opción Post-response, de esta nueva petición y pega:

pm.test("Status code es 201 Created", () => pm.expect(pm.response.code).to.equal(201));

Haz clic en Send de nuevo y confirma el ✅ en Test Results.

Consejo

200 significa “la petición funcionó”; 201 significa específicamente “se creó un recurso nuevo”. Por eso GET y PUT responden 200, pero un POST que crea algo responde 201. Vas a ver esta y otras aserciones de POST (el header Location, el id asignado) a fondo en Pruebas de API con Postman.

---

10. Exportar la Collection y el Environment a tu repositorio

Hasta ahora la Collection y el Environment solo existen en tu Postman local: si reinstalas la app o trabajas desde otro computador, los pierdes. Expórtalos y guárdalos junto con tu código, para que queden versionados como cualquier otro archivo del proyecto.

1. Haz clic derecho sobre la Collection → Export.
2. Elige el formato Collection v2.1 (el que Postman recomienda por defecto) y confirma.
3. Guarda el archivo .json descargado dentro de tu repositorio, en una carpeta collections/ en la raíz, con el nombre <Entidad>.postman_collection.json. Para el módulo de artistas: collections/Artista.postman_collection.json.
4. Ahora exporta también el Environment: en el selector de Environments, clic en el ícono de opciones (los tres puntos, junto al nombre del Environment) → Export.
5. Guarda ese archivo en la misma carpeta, como collections/environment.postman_environment.json.
6. Agrega los dos archivos a git y haz commit: git add collections/.

Consejo

Esta misma convención (collections/<Entidad>.postman_collection.json y collections/environment.postman_environment.json) es la que se va a verificar cuando integres tu módulo con el resto del equipo más adelante en el curso. Adoptarla desde ahora te ahorra ese ajuste después.

Consejo

Exportar el Environment versiona el nombre de la variable (baseUrl) junto con su valor, en vez de que cada quien la vuelva a escribir a mano. Vas a usar ese mismo archivo con Newman más adelante en el curso. Así te evitas errores tontos como escribir baseURL en un comando en vez de baseUrl, que harían que la variable simplemente no se resuelva.

10.1 Recuperarlas: importar

Cuando reinstales Postman o trabajes desde otro computador, haz el camino inverso: importa los archivos desde tu repositorio, primero la Collection y luego el Environment.

1. Abre el menú File → Import… (o pulsa Ctrl+O). Se abre el diálogo Use Resources, en la pestaña Import.
2. Abre en tu editor el archivo collections/Artista.postman_collection.json, selecciona todo su contenido (Ctrl+A), cópialo (Ctrl+C) y pégalo en el cuadro de texto de la parte de arriba del diálogo. Postman reconoce que es una Collection y la agrega a la barra lateral.
3. Repite con collections/environment.postman_environment.json: abre el diálogo de nuevo y pega su contenido. El Environment aparece en la sección Environments.
4. Selecciona ese Environment como en el paso 5, antes de enviar peticiones.

No pegues la ruta del archivo

El cuadro de texto espera el contenido del archivo, un enlace o un comando cURL, no la ruta de Windows. Si pegas C:\...\Artista.postman_collection.json, Postman responde “Incorrect format, please input the right format to import”.

Consejo

El diálogo también permite arrastrar un archivo hasta él o elegirlo con el enlace files, en vez de pegar su contenido. Hazlo de a un archivo: primero la Collection y luego el Environment.

---

¿Dónde quedaste?

Al final de este tutorial tienes una Collection en Postman con un Environment configurado, y dos peticiones guardadas usando {{baseUrl}}: GET /artistas (con un test que verifica 200 OK) y POST /artistas (con un test que verifica 201 Created). Tanto la Collection como el Environment ya quedaron exportados y versionados en tu repositorio, en collections/.

Lo que viene después:

• Pruebas de API con Postman: vas a profundizar en pm.expect(), encadenar peticiones (POST → GET → DELETE reutilizando el mismo id) y escribir escenarios positivos y negativos para PUT y DELETE.