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.

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. Crear una Collection

Una Collection en Postman es una carpeta que agrupa peticiones relacionadas, para que no queden sueltas ni se pierdan entre las de tus compañeros de curso.

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.

---

4. 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. Un Environment de Postman la guarda en una variable, para que cambiarla en un solo lugar actualice 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.

---

5. 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.

---

6. 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.

---

7. 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 Tests (al lado de Body) y pega:

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 4? Un error de conexión o una URL sin resolver hacen que el status nunca sea 200.

---

8. 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. Ábre la pestaña Tests 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.

---

¿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).

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.