Fundamentos de Postman para pruebas de APIs REST

Configurar el espacio de trabajo y entender el flujo básico

En Postman, el objetivo es convertir una intención de prueba (por ejemplo, “consultar un usuario” o “crear un recurso”) en una solicitud HTTP reproducible, con evidencia de resultado (respuesta) y criterios de validación. El flujo básico de prueba suele ser: definir request → enviar → inspeccionar respuesta → ajustar datos → validar → repetir.

Paso a paso: preparar un Workspace

• Crear/seleccionar un Workspace: usa un workspace dedicado al proyecto o al módulo de práctica (por ejemplo, “REST Fundamentals”).
• Crear una Collection: agrupa requests por recurso (Users, Posts, Orders) o por flujo (Auth, CRUD).
• Definir Variables: crea variables de colección para evitar “hardcodear” valores: {{baseUrl}}, {{token}}, {{userId}}.
• Configurar Authorization (si aplica): puedes definirla a nivel de colección para que hereden los requests (Bearer Token, API Key, etc.).
• Guardar ejemplos: tras ejecutar un request, guarda ejemplos de respuesta (Examples) para documentar comportamientos esperados.

Recomendación práctica: empieza con una variable {{baseUrl}} y construye todas las URLs a partir de ella. Esto facilita cambiar de entorno (local, staging, producción) sin editar cada request.

Estructura de una API REST y su traducción a requests

Una API REST suele organizarse por recursos (sustantivos) accesibles mediante URLs y manipulados con métodos HTTP. En Postman, cada request representa una operación sobre un recurso.

Componentes típicos

• Base URL: dominio + prefijo, por ejemplo https://api.ejemplo.com/v1.
• Path: ruta del recurso, por ejemplo /users o /users/123.
• Query params: filtros/paginación, por ejemplo ?page=1&limit=10.
• Headers: metadatos como Authorization, Content-Type, Accept.
• Body: datos enviados (común en POST/PUT/PATCH), normalmente JSON o form-data.

Mapa rápido: REST → Postman

Crear requests HTTP en Postman (GET, POST, PUT, PATCH, DELETE)

Para cada request, completa siempre: método, URL, params (si aplica), headers y body (si aplica). Luego guarda el request en la colección.

Convención de variables recomendada

• {{baseUrl}}: por ejemplo https://jsonplaceholder.typicode.com
• {{resourceId}}: id dinámico (por ejemplo, 1)
• {{token}}: token de autenticación si aplica

GET: listar recursos con query params

Objetivo: listar posts filtrando por usuario.

Continúa en nuestra aplicación.

• Escuche el audio con la pantalla apagada.
• Obtenga un certificado al finalizar.
• ¡Más de 5000 cursos para que explores!

O continúa leyendo más abajo...

Descargar la aplicación

• Método: GET
• URL: {{baseUrl}}/posts
• Params: userId=1
• Headers (opcional): Accept: application/json

En Postman, usa la pestaña Params para que Postman construya la query string automáticamente y evites errores de encoding.

GET: obtener un recurso por id

• Método: GET
• URL: {{baseUrl}}/posts/{{resourceId}}

Si {{resourceId}} no existe, lo común es recibir 404. Si existe, espera 200 y un JSON con campos del recurso.

POST: crear recurso con body JSON

Objetivo: crear un post.

• Método: POST
• URL: {{baseUrl}}/posts
• Headers: Content-Type: application/json
• Body (raw → JSON):

{"title":"Post de prueba","body":"Contenido","userId":1}

Criterio práctico: en creación, es frecuente recibir 201 (Created) y un objeto con un id asignado. Algunas APIs devuelven 200 con el recurso creado; valida según el contrato.

PUT: reemplazo completo

Objetivo: reemplazar el post completo. En PUT, envía el recurso “completo” según el esquema esperado.

• Método: PUT
• URL: {{baseUrl}}/posts/{{resourceId}}
• Headers: Content-Type: application/json
• Body:

{"id":1,"title":"Título actualizado","body":"Texto actualizado","userId":1}

Fallo común: enviar campos incompletos en PUT cuando la API espera el recurso completo, provocando 400 o pérdida de datos (si el backend interpreta ausencias como null).

PATCH: actualización parcial

Objetivo: cambiar solo el título.

• Método: PATCH
• URL: {{baseUrl}}/posts/{{resourceId}}
• Headers: Content-Type: application/json
• Body:

{"title":"Solo cambio el título"}

Criterio práctico: valida que el campo modificado cambió y que los demás campos permanecen consistentes.

DELETE: eliminar recurso

• Método: DELETE
• URL: {{baseUrl}}/posts/{{resourceId}}

Respuestas típicas: 200 con body, 204 sin body. Valida el código y, si el contrato lo indica, confirma que el recurso ya no existe con un GET posterior (debería dar 404).

Definir URL, query params, headers y body (JSON y form-data)

URL y Path variables

Usa variables para IDs y base URL. Ejemplo:

{{baseUrl}}/users/{{userId}}/orders

Checklist rápida: ¿la variable existe en el scope correcto (Environment/Collection)? ¿tiene el valor esperado? ¿se está resolviendo (Postman muestra el valor al pasar el cursor)?

Query params

Úsalos para filtrar, ordenar y paginar. Ejemplos comunes:

• page=1, limit=20
• sort=-createdAt
• status=active

Fallo común: enviar valores con espacios o caracteres especiales sin encoding; al usar la pestaña Params, Postman lo gestiona mejor.

Headers esenciales

• Content-Type: indica el formato del body enviado (por ejemplo, application/json).
• Accept: formato esperado en la respuesta (por ejemplo, application/json).
• Authorization: credenciales (por ejemplo, Bearer {{token}}).
• X-Request-Id (opcional): útil para trazabilidad si el backend lo soporta.

Fallo común: enviar JSON pero olvidar Content-Type: application/json, provocando 415 (Unsupported Media Type) o parseo incorrecto.

Body JSON (raw)

Ideal para APIs REST modernas. En Postman: Body → raw → JSON. Valida que el JSON sea válido y que los tipos coincidan (número vs string, boolean, arrays).

Body form-data

Útil cuando el endpoint espera campos tipo formulario o subida de archivos. En Postman: Body → form-data.

• Campos texto: name=Ana, role=admin
• Archivo: selecciona tipo File en la fila correspondiente

Fallo común: mezclar form-data con Content-Type fijado manualmente; deja que Postman lo gestione para incluir el boundary correcto.

Ejecutar solicitudes y leer la respuesta

Tras pulsar Send, Postman muestra información clave para evaluar el resultado.

Qué revisar en la respuesta

• Status code: indica el resultado general (2xx éxito, 4xx error del cliente, 5xx error del servidor).
• Response time: útil para detectar degradaciones o endpoints lentos.
• Response size: ayuda a identificar respuestas inesperadamente grandes o vacías.
• Headers de respuesta: por ejemplo Content-Type, Cache-Control, Location (en creaciones), WWW-Authenticate (en 401).
• Body: valida estructura, campos, mensajes de error, y consistencia con el request.

Interpretación práctica de status codes comunes

Criterios prácticos para validar respuestas y detectar fallos comunes

Validaciones mínimas recomendadas por request

• Código esperado: define el rango aceptable (por contrato).
• Content-Type: normalmente application/json en APIs REST.
• Estructura del JSON: campos obligatorios presentes.
• Tipos de datos: id numérico, fechas en formato esperado, booleanos reales.
• Reglas de negocio: por ejemplo, email único, status en un conjunto permitido.
• Consistencia: si creas un recurso, luego un GET debería reflejarlo (cuando el sistema no es eventual).

Fallos comunes y cómo diagnosticarlos

• Errores de autenticación (401): revisa que Authorization esté presente, que el token no esté expirado, y que el prefijo sea correcto (Bearer vs otro). Verifica si el backend devuelve WWW-Authenticate.
• Permisos insuficientes (403): el token es válido, pero el usuario/cliente no tiene permisos. Revisa roles/scopes y el endpoint correcto.
• Recurso inexistente (404): confirma la URL, versión (/v1), y el id. Si el id viene de una variable, verifica su valor actual.
• Validación de payload (400/422): revisa campos requeridos, longitudes, formatos (email), y tipos. Asegúrate de enviar Content-Type correcto y JSON válido.
• Errores por headers: 415 por media type, o respuestas no JSON por Accept incorrecto.
• Datos no persistidos: si un POST responde éxito pero el GET no refleja cambios, puede ser un entorno mock, consistencia eventual, o un endpoint que no persiste (verifica documentación del endpoint).

Ejercicios guiados con endpoints de ejemplo

Usa estos endpoints públicos para practicar CRUD sin necesidad de credenciales. Define {{baseUrl}} como https://jsonplaceholder.typicode.com.

Ejercicio 1: GET listado con filtro

Request: GET {{baseUrl}}/posts con userId=1.

• Checklist:
  • ¿Status es 200?
  • ¿Content-Type incluye application/json?
  • ¿El body es un array?
  • ¿Todos los elementos tienen userId=1?
  • ¿Tiempo de respuesta razonable (por ejemplo < 1500 ms)?

Ejercicio 2: GET por id y manejo de 404

Request A: GET {{baseUrl}}/posts/1. Request B: GET {{baseUrl}}/posts/999999.

• Checklist A:
  • ¿Status 200?
  • ¿Existe id y es 1?
  • ¿Campos title y body presentes?
• Checklist B:
  • ¿Status es 404 o un comportamiento documentado equivalente?
  • ¿El body de error (si existe) es consistente?

Ejercicio 3: POST con JSON y validación de respuesta

Request: POST {{baseUrl}}/posts con body JSON.

{"title":"Nuevo","body":"Texto","userId":1}

• Checklist:
  • ¿Status es 201 o 200 según el servicio?
  • ¿La respuesta incluye id?
  • ¿La respuesta refleja title, body, userId enviados?
  • ¿Content-Type correcto?

Ejercicio 4: PUT vs PATCH (diferencia práctica)

Request PUT: PUT {{baseUrl}}/posts/1 enviando objeto completo. Request PATCH: PATCH {{baseUrl}}/posts/1 enviando solo {"title":"X"}.

• Checklist:
  • ¿Ambos devuelven status exitoso?
  • ¿PUT devuelve un recurso “completo”?
  • ¿PATCH modifica solo el campo enviado?
  • ¿Se mantienen tipos de datos?

Ejercicio 5: DELETE y verificación posterior

Request: DELETE {{baseUrl}}/posts/1. Luego ejecuta GET {{baseUrl}}/posts/1.

• Checklist:
  • ¿DELETE devuelve 200 o 204?
  • ¿El GET posterior refleja eliminación (si el servicio realmente persiste)?
  • Si no refleja, ¿estás en un endpoint de prueba que simula operaciones?

Checklists reutilizables por tipo de request

Checklist para GET

• URL correcta (baseUrl + path) y params en pestaña Params
• Status esperado (200 o 304 si aplica cache)
• Body con estructura esperada (array/objeto)
• Campos obligatorios presentes
• Tiempo y tamaño razonables

Checklist para POST/PUT/PATCH

• Content-Type correcto
• Body válido (JSON bien formado o form-data correcto)
• Status esperado (201/200)
• Respuesta refleja cambios (campos actualizados)
• Validación de errores: prueba un payload inválido y verifica 400/422

Checklist para DELETE

• Status esperado (200/204)
• Body vacío si es 204
• Verificación posterior (GET) si el sistema persiste
• Manejo de id inexistente (espera 404 o comportamiento documentado)