Guía de pruebas de API: desde los fundamentos hasta flujos de trabajo automatizados

Las APIs son los contratos entre sistemas de software. Cuando una API falla, todo lo que depende de ella también falla. Sin embargo, las pruebas de API suelen tratarse como algo secundario: algo que se hace manualmente en una pestaña del navegador justo antes del despliegue. Una estrategia de pruebas adecuada detecta errores temprano, documenta el comportamiento esperado y te da la confianza necesaria para lanzar.

¿Qué es una prueba de API?

Una prueba de API envía una solicitud HTTP y verifica algo sobre la respuesta:

• Código de estado — ¿Recibimos 200 OK o 404 Not Found?
• Cuerpo de la respuesta — ¿Es correcta la estructura de datos? ¿Son correctos los valores?
• Cabeceras — ¿Está Content-Type configurado correctamente? ¿Está presente la cabecera de autenticación?
• Tiempo de respuesta — ¿Responde el endpoint dentro de un margen aceptable?
• Manejo de errores — ¿Qué ocurre con entradas incorrectas? ¿Obtenemos errores informativos?

Códigos de estado HTTP que debes conocer

Código	Significado	Cuándo lo verás
200	OK	GET, PUT, PATCH exitosos
201	Created	POST exitoso que crea un recurso
204	No Content	DELETE exitoso o acción sin cuerpo
400	Bad Request	Entrada inválida, JSON malformado, campos faltantes
401	Unauthorized	Token de autenticación ausente o inválido
403	Forbidden	Autenticado pero sin autorización
404	Not Found	El recurso no existe
409	Conflict	Recurso duplicado, conflicto de versión
422	Unprocessable Entity	Errores de validación en JSON válido
429	Too Many Requests	Límite de solicitudes superado
500	Internal Server Error	Error en el lado del servidor
503	Service Unavailable	Servidor caído o sobrecargado

401 significa "¿quién eres?" — 403 significa "sé quién eres, pero no puedes hacer eso."

Pruebas manuales con el API Request Builder

Antes de automatizar, comprende tus endpoints manualmente. Nuestro API Request Builder te permite:

• Establecer el método HTTP (GET, POST, PUT, PATCH, DELETE)
• Agregar cabeceras (Authorization, Content-Type, cabeceras personalizadas)
• Construir parámetros de consulta sin codificar la URL manualmente
• Escribir un cuerpo de solicitud JSON con resaltado de sintaxis
• Inspeccionar la respuesta completa, incluidas cabeceras y tiempos

Es ideal para explorar una nueva API, depurar un endpoint específico o verificar rápidamente una corrección.

Pruebas de REST APIs: el ciclo CRUD completo

Para una API /users hipotética, una suite de pruebas completa cubre:

Crear (POST)

POST /users
Content-Type: application/json

{
  "name": "Alice Chen",
  "email": "alice@example.com",
  "role": "editor"
}

Verificar:

• Estado 201 Created
• El cuerpo de la respuesta contiene el usuario creado con un id generado
• La cabecera Location apunta al nuevo recurso (p. ej., /users/42)

Leer (GET)

GET /users/42
Authorization: Bearer <token>

Verificar:

• Estado 200 OK
• El cuerpo coincide con el usuario creado
• El id es 42

Actualizar (PUT / PATCH)

PATCH /users/42
Content-Type: application/json

{ "role": "admin" }

Verificar:

• Estado 200 OK
• El campo role ahora es "admin" en la respuesta
• Los demás campos no han cambiado

Eliminar (DELETE)

DELETE /users/42
Authorization: Bearer <token>

Verificar:

• Estado 204 No Content
• Un GET /users/42 posterior devuelve 404

Pruebas negativas: las pruebas que la mayoría omite

Las pruebas positivas verifican el camino feliz. Las pruebas negativas verifican que la API maneje entradas incorrectas de forma controlada:

• Campos requeridos faltantes → 400 con mensaje de error claro
• Tipos de datos inválidos ("age": "twenty") → 400
• Recurso inexistente (GET /users/99999) → 404
• Token caducado → 401
• Acceso a datos de otro usuario → 403
• Envío de un payload de 10 MB → 413 Payload Too Large
• Superar los límites de solicitudes → 429 con cabecera Retry-After

Una API bien diseñada falla de forma predecible e informativa.

Patrones de pruebas de autenticación

Tokens Bearer (JWT)

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Escenarios de prueba:

• Token válido → respuesta correcta
• Token caducado → 401 con mensaje "Token expired"
• Token manipulado (cambiar un carácter) → 401
• Cabecera ausente → 401
• Token de un entorno diferente → 401

Usa nuestro JWT Decoder para inspeccionar tokens y verificar tiempos de expiración durante las pruebas manuales.

Claves de API

X-API-Key: sk_live_abc123

Prueba: clave incorrecta, clave ausente, clave con permisos insuficientes.

Flujos OAuth 2.0

OAuth añade complejidad — prueba los endpoints de intercambio de tokens por separado de los endpoints de recursos.

Validación de cuerpos de respuesta

No te limites a verificar los códigos de estado. Valida la estructura de las respuestas:

// Using Jest + supertest
test("GET /users/:id returns the correct user", async () => {
  const response = await request(app).get("/users/42").set("Authorization", `Bearer ${token}`);

  expect(response.status).toBe(200);
  expect(response.headers["content-type"]).toMatch(/json/);
  expect(response.body).toMatchObject({
    id: 42,
    name: expect.any(String),
    email: expect.stringMatching(/^[^\s@]+@[^\s@]+\.[^\s@]+$/),
    role: expect.oneOf(["admin", "editor", "viewer"]),
  });
});

Para esquemas de respuesta más grandes, usa la validación con JSON Schema a través de nuestro JSON Schema Validator para definir la forma esperada una sola vez y probar todos los endpoints contra ella.

Pruebas de contrato

En microservicios, las pruebas de contrato garantizan que un consumidor y un proveedor estén de acuerdo en la forma de la API. El consumidor define lo que necesita; el proveedor verifica que lo cumple. Herramientas como Pact automatizan este proceso.

Esto es especialmente valioso cuando distintos equipos son responsables de diferentes servicios: una prueba de contrato falla inmediatamente cuando se cambia el nombre de un campo o se elimina, antes de la integración.

Pruebas de rendimiento y carga

Las pruebas funcionales te dicen si la API funciona. Las pruebas de rendimiento te dicen qué tan bien funciona bajo carga:

• Línea base — ¿Cuál es el tiempo de respuesta p50/p95/p99 con un solo usuario?
• Prueba de carga — ¿Cómo se comporta con el tráfico pico esperado?
• Prueba de estrés — ¿En qué punto comienza a fallar?
• Prueba de picos — ¿Qué ocurre con un aumento repentino de tráfico de 10×?

Un objetivo habitual: < 200ms para p95 en la carga pico esperada.

Lista de verificación para pruebas de API

• Probar todas las operaciones CRUD para cada recurso
• Probar casos negativos: entrada inválida, autenticación ausente, recurso no encontrado
• Validar los cuerpos de respuesta contra un esquema (no solo los códigos de estado)
• Probar casos límite de autenticación: tokens caducados, ausentes o manipulados
• Verificar que las respuestas de error tengan mensajes útiles
• Comprobar que la paginación, el filtrado y la ordenación funcionen correctamente
• Probar el comportamiento ante límites de solicitudes
• Verificar que no se filtren datos sensibles en las respuestas de error
• Comprobar el tiempo de respuesta bajo la carga esperada

Las buenas pruebas de API son tu red de seguridad para la refactorización y la mejor documentación que puedes tener: muestran exactamente qué hace cada endpoint y qué espera recibir.