Guía de Pruebas y Depuración de API: De cURL a Herramientas en Línea

Herramientas de desarrollo

Métodos de Solicitud HTTP

Método Uso Idempotente Seguro
GET Obtener recurso ✅ ✅
POST Crear recurso ❌ ❌
PUT Actualización completa ✅ ❌
PATCH Actualización parcial ❌ ❌
DELETE Eliminar recurso ✅ ❌
HEAD Obtener encabezados ✅ ✅
OPTIONS Preflight CORS ✅ ✅

Encabezados de Solicitud Comunes

Encabezado Descripción Ejemplo
Content-Type Formato del cuerpo application/json
Accept Formato de respuesta esperado application/json
Authorization Información de autenticación Bearer token...
User-Agent Identificación del cliente Mozilla/5.0...
Cookie Cookie session=abc123
X-Request-ID ID de seguimiento de solicitud UUID

Valores Comunes de Content-Type

Valor Uso
application/json Datos JSON
application/x-www-form-urlencoded Datos de formulario
multipart/form-data Subida de archivos
text/plain Texto plano
text/html HTML

Métodos de Autenticación

1. Bearer Token (el más usado)

# cURL
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..." \
  https://api.example.com/users

# JavaScript
fetch('https://api.example.com/users', {
  headers: {
    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiJ9...',
  },
});

2. Basic Auth

# cURL (codificación automática)
curl -u username:password https://api.example.com/users

# Codificación manual
# Base64("username:password") = "dXNlcm5hbWU6cGFzc3dvcmQ="
curl -H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" \
  https://api.example.com/users

3. API Key

# Método 1: Header
curl -H "X-API-Key: your-api-key" \
  https://api.example.com/users

# Método 2: Parámetro de consulta
curl "https://api.example.com/users?api_key=your-api-key"

Detalle del Comando cURL

Solicitud GET Básica

# GET más simple
curl https://api.example.com/users

# Mostrar encabezados de respuesta
curl -i https://api.example.com/users

# Solo mostrar encabezados de respuesta
curl -I https://api.example.com/users

# Seguir redirecciones
curl -L https://example.com/redirect

Solicitud POST

# Datos JSON
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "email": "alice@example.com"}'

# Datos de formulario
curl -X POST https://api.example.com/users \
  -d "name=Alice&email=alice@example.com"

# Subida de archivo
curl -X POST https://api.example.com/upload \
  -F "file=@photo.jpg" \
  -F "description=My photo"

Opciones Avanzadas

# Configuración de tiempo de espera
curl --connect-timeout 5 --max-time 30 https://api.example.com

# Guardar en archivo
curl -o response.json https://api.example.com/users

# Modo silencioso (sin barra de progreso)
curl -s https://api.example.com/users

# Salida detallada (para depuración)
curl -v https://api.example.com/users

# Ignorar verificación de certificado SSL (solo entorno de desarrollo)
curl -k https://self-signed.example.com

# Proxy
curl -x http://proxy:8080 https://api.example.com

# Cookie
curl -b "session=abc123" https://api.example.com/users

# Guardar y enviar Cookie
curl -c cookies.txt -b cookies.txt https://api.example.com/users

Códigos de Estado HTTP Comunes

Código Significado Causa Común
200 OK Éxito
201 Created POST creado exitosamente
204 No Content DELETE exitoso
301 Moved Permanently Redirección permanente
304 Not Modified Caché acertada
400 Bad Request Parámetros incorrectos
401 Unauthorized No autenticado
403 Forbidden Sin permisos
404 Not Found Recurso no existe
409 Conflict Conflicto de recurso
422 Unprocessable Entity Validación fallida
429 Too Many Requests Limitación de tasa
500 Internal Server Error Error del servidor
502 Bad Gateway Servicio upstream no disponible
503 Service Unavailable Servicio sobrecargado

Usar ToolsKu para Probar API

Convertir cURL a Código

  1. Abrir Herramienta cURL a Código
  2. Pegar el comando cURL
  3. Seleccionar el lenguaje destino (JavaScript/Python/Go/Java, etc.)
  4. Copiar el código generado

Ejemplo

# Entrada cURL
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer token123" \
  -d '{"name": "Alice"}'

Convertido a JavaScript:

const response = await fetch('https://api.example.com/users', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer token123',
  },
  body: JSON.stringify({ name: 'Alice' }),
});
const data = await response.json();

Técnicas de Depuración de API

1. Ver Solicitud/Respuesta Completa

# -v muestra información detallada
curl -v https://api.example.com/users

# Salida:
> GET /users HTTP/1.1          ← Línea de solicitud
> Host: api.example.com        ← Encabezado de solicitud
> Authorization: Bearer ...
>
< HTTP/1.1 200 OK              ← Línea de respuesta
< Content-Type: application/json ← Encabezado de respuesta
< X-RateLimit-Remaining: 99
<
[{"id": 1, "name": "Alice"}]   ← Cuerpo de respuesta

2. Formatear Respuesta JSON

# Usar jq para formatear
curl -s https://api.example.com/users | jq

# Usar python
curl -s https://api.example.com/users | python -m json.tool

# O usar la herramienta de formateo JSON de ToolsKu

3. Medir Tiempo de Respuesta

# Estadísticas detalladas de tiempo
curl -w "DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTTFB: %{time_starttransfer}s\nTotal: %{time_total}s\n" \
  -o /dev/null -s https://api.example.com/users

# Salida:
# DNS: 0.012s
# Connect: 0.035s
# TTFB: 0.120s
# Total: 0.125s

4. Solucionar Problemas de CORS

Error del navegador:
Access to fetch at 'https://api.example.com' from origin 'https://app.example.com'
has been blocked by CORS policy

Pasos para solucionar:
1. Verificar solicitud preflight OPTIONS
   curl -X OPTIONS -H "Origin: https://app.example.com" \
     -H "Access-Control-Request-Method: POST" \
     -i https://api.example.com/users

2. Verificar encabezados de respuesta
   Access-Control-Allow-Origin: https://app.example.com
   Access-Control-Allow-Methods: GET, POST, PUT, DELETE
   Access-Control-Allow-Headers: Content-Type, Authorization
   Access-Control-Max-Age: 86400

5. Solucionar Problemas de Autenticación

Solución de 401 Unauthorized:
1. ¿El Token expiró? → Usar herramienta de decodificación JWT para verificar exp
2. ¿El formato del Token es correcto? → Verificar prefijo Bearer
3. ¿Se envió el Token? → curl -v verificar encabezados de solicitud

Solución de 403 Forbidden:
1. ¿El usuario tiene permisos? → Verificar rol del usuario
2. ¿La IP está en la lista blanca? → Verificar registros del servidor
3. ¿Se excedió el límite de frecuencia? → Verificar código de estado 429

Mejores Prácticas de Pruebas de API

1. Gestión de Variables de Entorno

# Usar variables de entorno para almacenar información sensible
export API_BASE="https://api.example.com"
export API_TOKEN="your-token"

curl -H "Authorization: Bearer $API_TOKEN" "$API_BASE/users"

2. Colección de Solicitudes

#!/bin/bash
# api-test.sh

BASE="https://api.example.com"
TOKEN="Bearer $API_TOKEN"
HEADER="-H 'Content-Type: application/json' -H 'Authorization: $TOKEN'"

# Obtener lista de usuarios
get_users() { curl -s $HEADER "$BASE/users" | jq; }

# Crear usuario
create_user() { curl -s -X POST $HEADER -d "$1" "$BASE/users" | jq; }

# Obtener un usuario
get_user() { curl -s $HEADER "$BASE/users/$1" | jq; }

# Uso
get_users
create_user '{"name":"Bob"}'
get_user 1

3. Pruebas Automatizadas

// Escribir pruebas de API con fetch
async function testApi() {
  // Probar GET
  const listRes = await fetch('/api/users');
  console.assert(listRes.status === 200, 'GET /users should return 200');

  // Probar POST
  const createRes = await fetch('/api/users', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ name: 'Test' }),
  });
  console.assert(createRes.status === 201, 'POST /users should return 201');

  const created = await createRes.json();
  console.assert(created.name === 'Test', 'Name should match');
}

Preguntas Frecuentes

¿Problemas con las comillas de cURL en Windows?

Windows CMD usa comillas dobles, PowerShell tiene problemas de escape:

# En PowerShell, cURL es un alias de Invoke-WebRequest
# Usar curl.exe para invocar el cURL real
curl.exe -X POST https://api.example.com/users `
  -H "Content-Type: application/json" `
  -d '{\"name\": \"Alice\"}'

¿Cómo solucionar tiempos de espera?

1. ¿DNS lento? → curl -w verificar time_namelookup
2. ¿Conexión lenta? → curl -w verificar time_connect
3. ¿Procesamiento del servidor lento? → curl -w verificar time_starttransfer - time_connect
4. ¿Transmisión de respuesta lenta? → curl -w verificar time_total - time_starttransfer

Resumen

La depuración de API es parte del día a día del desarrollador: dominar los comandos cURL, los códigos de estado HTTP, los métodos de autenticación y las técnicas de depuración permite localizar rápidamente problemas de interfaz. La Herramienta cURL a Código y la Herramienta de Formateo JSON de ToolsKu son excelentes compañeras para la depuración de API, ayudándote a probar interfaces y revisar respuestas rápidamente.

#API testing#HTTP requests#cURL#API debugging#tutorial