Documentación API para Testers: Ejemplos Request/Response y Estrategias de Prueba

La documentación API para equipos QA requiere enfoque diferente que documentación para desarrolladores. Los testers necesitan ejemplos comprehensivos, escenarios de error, flujos de autenticación y casos extremos—no solo documentación de camino feliz.

Componentes Esenciales para Documentación API Orientada a QA

1. Autenticación y Autorización

Documentar todos los métodos de auth con credenciales de prueba:

## Autenticación

### Método: Bearer Token (JWT)

**Obtener un Token**:
```http
POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "test@example.com",
  "password": "Test123!"
}

Respuesta:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600
}

Cuentas de Usuario de Prueba

### 2. Ejemplos Request/Response para Todos los Escenarios

**Casos de Éxito**:
```markdown
## Crear Pedido - Éxito

**Request**:
```http
POST /api/v1/orders
Authorization: Bearer {token}
Content-Type: application/json

{
  "items": [
    {"product_id": 101, "quantity": 2}
  ],
  "shipping_address": {
    "street": "Calle Principal 123",
    "city": "Barcelona"
  }
}

Response: 201 Created:

{
  "id": 789,
  "status": "pending",
  "total": 129.99
}

Casos de Error:

400 Bad Request - Datos Inválidos:

POST /api/v1/orders
{
  "items": []  // Array vacío
}

Response:

{
  "error": "validation_error",
  "message": "Datos de solicitud inválidos",
  "details": [
    {"field": "items", "error": "debe contener al menos un ítem"}
  ]
}

401 Unauthorized - Token Inválido:

{
  "error": "unauthorized",
  "message": "Token de autenticación inválido o expirado"
}

403 Forbidden - Permisos Insuficientes:

{
  "error": "forbidden",
  "message": "Permisos insuficientes"
}

404 Not Found:

{
  "error": "not_found",
  "message": "Pedido con ID 99999 no encontrado"
}

3. Referencia de Códigos de Error

## Códigos de Error

| Código HTTP | Código Error | Descripción | Escenario de Prueba |
|------------|-------------|-------------|-------------------|
| 400 | validation_error | Validación de datos falló | Enviar campos inválidos/faltantes |
| 401 | unauthorized | Autenticación requerida o inválida | Sin token, token expirado |
| 403 | forbidden | Permisos insuficientes | Cliente intenta operación admin |
| 404 | not_found | Recurso no existe | Solicitar ID inexistente |
| 409 | conflict | Conflicto de estado | Creación duplicada |
| 429 | rate_limit_exceeded | Demasiadas solicitudes | Exceder 1000 req/hora |
| 500 | internal_server_error | Error del servidor | Probar estado backend inválido |

4. Colección Postman

Exportar colección para testers:

{
  "info": {
    "name": "E-commerce API - Colección QA"
  },
  "item": [
    {
      "name": "Autenticación",
      "item": [
        {
          "name": "Login - Éxito",
          "request": {
            "method": "POST",
            "url": "{{base_url}}/api/v1/auth/login"
          }
        }
      ]
    }
  ]
}

5. Límites de Tasa

## Rate Limiting

**Límites**:
- No autenticados: 100 solicitudes/hora
- Usuarios autenticados: 1,000 solicitudes/hora

**Prueba de Límites de Tasa**:
```bash
for i in {1..1001}; do
  curl -H "Authorization: Bearer $TOKEN" \
    https://api.example.com/v1/products
done

Comportamiento Esperado:

• Solicitud 1-1000: 200 OK
• Solicitud 1001: 429 Too Many Requests

### 6. Reglas de Validación de Datos

```markdown
## Validación de Campos

| Campo | Tipo | Requerido | Restricciones | Ejemplos Inválidos |
|-------|------|-----------|---------------|-------------------|
| name | string | Sí | 1-200 chars | "", "a", (201 chars) |
| price | number | Sí | > 0 | 0, -10 |
| category | string | Sí | [electronics, clothing] | "invalid" |

7. Idempotencia y Concurrencia

## Idempotencia

**Operaciones Idempotentes**:
- GET, PUT, DELETE

**No Idempotentes** (requieren claves):
- POST /api/v1/orders

**Usando Claves de Idempotencia**:
```http
POST /api/v1/orders
Idempotency-Key: unique-key-123

Prueba de Idempotencia:

1. Enviar POST con clave de idempotencia
2. Repetir solicitud idéntica con misma clave
3. Esperado: Segunda solicitud devuelve mismo resultado

## Mejores Prácticas

### 1. Documentar Casos Extremos Explícitamente

No solo mostrar caminos felices. Incluir:
- Valores límite
- Tipos de datos inválidos
- Campos requeridos faltantes

### 2. Proporcionar Ejemplos cURL

```bash
curl -X POST https://api.example.com/v1/orders \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"product_id": 101}]}'

3. Incluir Variables de Entorno

BASE_URL=https://staging.api.example.com
TEST_EMAIL=test@example.com

Conclusión

La documentación API efectiva para QA va más allá de describir endpoints—proporciona escenarios completos de prueba, casos de error, flujos de autenticación y reglas de validación. Al incluir colecciones Postman, mock servers y ejemplos de casos extremos, los equipos permiten a los testers crear rápidamente suites de prueba comprehensivas.