Formatos de Respuesta API: Mejores Prácticas para APIs Consistentes
Las respuestas API inconsistentes son una de las principales quejas de los desarrolladores frontend. Cuando cada endpoint devuelve datos con una estructura diferente, el código del cliente se llena de casos especiales. Un formato de respuesta consistente mejora la experiencia del desarrollador, reduce errores y hace que tu API se auto-documente.
El Envoltorio de Respuesta
Envuelve cada respuesta en una estructura consistente:
Éxito (Recurso Individual)
{
"data": {
"id": "user_123",
"name": "Alice",
"email": "[email protected]",
"createdAt": "2024-01-15T10:30:00Z"
},
"meta": {
"requestId": "req_abc123"
}
}
Éxito (Colección)
{
"data": [
{ "id": "user_123", "name": "Alice" },
{ "id": "user_456", "name": "Bob" }
],
"meta": {
"total": 142,
"page": 1,
"perPage": 20,
"requestId": "req_def456"
}
}
Error
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"details": [
{ "field": "email", "message": "Invalid email format" }
]
},
"meta": {
"requestId": "req_ghi789"
}
}
El principio clave: los clientes siempre verifican data o error en el nivel superior. Nunca mezcles datos exitosos e información de error en la misma respuesta.
Valida tu formato de respuesta con nuestro JSON Validator.
Códigos de Estado HTTP
Usa los códigos de estado correctamente — son lo primero que verifican los clientes:
Códigos de Éxito
| Código | Cuándo |
|---|---|
| 200 OK | Éxito en GET, éxito en PUT/PATCH |
| 201 Created | POST que creó un recurso |
| 204 No Content | Éxito en DELETE (sin cuerpo) |
Códigos de Error del Cliente
| Código | Cuándo |
|---|---|
| 400 Bad Request | Sintaxis de solicitud malformada |
| 401 Unauthorized | Autenticación faltante o inválida |
| 403 Forbidden | Autenticado pero no autorizado |
| 404 Not Found | El recurso no existe |
| 409 Conflict | Conflicto de estado del recurso (duplicado) |
| 422 Unprocessable | Sintaxis válida pero errores semánticos |
| 429 Too Many Requests | Límite de tasa excedido |
Códigos de Error del Servidor
| Código | Cuándo |
|---|---|
| 500 Internal Server Error | Fallo inesperado del servidor |
| 502 Bad Gateway | Fallo del servicio upstream |
| 503 Service Unavailable | Sobrecarga temporal o mantenimiento |
Diseño de Respuestas de Error
Las buenas respuestas de error ayudan a los desarrolladores a depurar rápidamente:
{
"error": {
"code": "RESOURCE_NOT_FOUND",
"message": "User with ID 'user_999' not found",
"details": [],
"documentationUrl": "https://api.example.com/docs/errors#RESOURCE_NOT_FOUND"
},
"meta": {
"requestId": "req_xyz789",
"timestamp": "2024-01-15T10:30:00Z"
}
}
Reglas:
codees legible por máquinas (cadena constante, no el estado HTTP)messagees legible por humanos (puede cambiar sin romper clientes)detailsproporciona errores a nivel de campo para fallos de validaciónrequestIdpermite al equipo de soporte rastrear la solicitud en los logs
Patrones de Paginación
Basada en Offset
Simple y permite saltar a páginas arbitrarias:
{
"data": ["..."],
"meta": {
"page": 2,
"perPage": 20,
"total": 142,
"totalPages": 8
},
"links": {
"first": "/api/users?page=1&per_page=20",
"prev": "/api/users?page=1&per_page=20",
"next": "/api/users?page=3&per_page=20",
"last": "/api/users?page=8&per_page=20"
}
}
Basada en Cursor
Mejor para datos en tiempo real y conjuntos de datos grandes:
{
"data": ["..."],
"meta": {
"hasNext": true,
"hasPrev": true
},
"links": {
"next": "/api/users?cursor=eyJpZCI6MTQzfQ&limit=20",
"prev": "/api/users?cursor=eyJpZCI6MTIzfQ&limit=20&direction=prev"
}
}
Fecha y Hora
Siempre usa ISO 8601 con información de zona horaria:
{
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T14:22:33+00:00",
"expiresAt": "2024-12-31T23:59:59Z"
}
Nunca uses:
- Timestamps Unix (ambiguos: ¿segundos o milisegundos?)
- Fechas locales sin zona horaria
- Formatos personalizados como MM/DD/YYYY
Para más información sobre el manejo de timestamps, consulta nuestra guía de Timestamps Unix.
Null vs Campos Ausentes
Dos enfoques comunes:
Incluir con null (explícito):
{ "name": "Alice", "avatar": null, "bio": null }
Omitir campos ausentes (disperso):
{ "name": "Alice" }
Recomendación: Sé consistente dentro de tu API. Los nulls explícitos son mejores para lenguajes tipados (los clientes saben que el campo existe). El enfoque disperso es mejor para entornos con restricciones de ancho de banda.
Versionado de Respuestas
Cuando el formato de respuesta cambia, versiona tu API:
GET /api/v2/users/123
Cambios que rompen compatibilidad y requieren versionado:
- Eliminar un campo
- Cambiar el tipo de un campo
- Renombrar un campo
- Cambiar la estructura del envoltorio de respuesta
Cambios no disruptivos (seguros sin versionado):
- Agregar nuevos campos
- Agregar nuevos endpoints
- Agregar nuevos valores de enum
FAQ
¿Debería envolver las respuestas exitosas en una clave data o devolver el recurso directamente?
Usar un envoltorio data proporciona una estructura consistente para todas las respuestas y deja espacio para metadatos, paginación y enlaces junto a los datos. Devolver el recurso directamente es más simple para endpoints de recurso individual. La mayoría de las APIs modernas usan el enfoque de envoltorio por consistencia.
¿Cómo debo manejar los fallos parciales en operaciones por lotes?
Devuelve 200 con una respuesta que incluya tanto éxitos como fallos en el objeto data. Usar 207 Multi-Status (WebDAV) es otra opción pero se usa menos comúnmente en APIs REST.
Nomenclatura de Recursos
Los recursos son sustantivos, no verbos. Usa sustantivos en plural para colecciones y recursos individuales mediante ID:
GET /api/users # List users
POST /api/users # Create a user
GET /api/users/123 # Get user 123
PUT /api/users/123 # Update user 123
DELETE /api/users/123 # Delete user 123
Convenciones de nomenclatura:
- Usa minúsculas con guiones:
/api/blog-posts(noblogPostsniblog_posts) - Anida recursos relacionados:
/api/users/123/orders - Limita la anidación a 2 niveles:
/api/users/123/orders/456(no más profundo) - Evita verbos en URLs:
/api/users/123/activatees aceptable para acciones que no se mapean a CRUD
Filtrado y Ordenamiento
Filtrado
GET /api/users?status=active&role=admin
GET /api/users?created_after=2024-01-01
GET /api/users?search=alice
Para filtros complejos, considera un parámetro de consulta dedicado:
GET /api/users?filter[status]=active&filter[role]=admin
Ordenamiento
GET /api/users?sort=name # Ascendente
GET /api/users?sort=-created_at # Descendente (prefijo con -)
GET /api/users?sort=-created_at,name # Múltiples campos
Limitación de Tasa
Comunica los límites de tasa en los headers de respuesta:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 67
X-RateLimit-Reset: 1705312800
Retry-After: 30
Devuelve 429 Too Many Requests cuando se exceda el límite, con un mensaje de error claro y el header Retry-After.
HATEOAS (Opcional pero Poderoso)
Incluye enlaces a recursos y acciones relacionadas:
{
"data": {
"id": "123",
"name": "Alice",
"links": {
"self": "/api/users/123",
"orders": "/api/users/123/orders",
"avatar": "/api/users/123/avatar"
}
}
}
Esto hace que tu API sea auto-documentada y reduce la construcción de URLs del lado del cliente.
FAQ
¿Cómo debo manejar actualizaciones parciales (PATCH vs PUT)?
Usa PUT para reemplazo completo de recursos (el cliente envía todos los campos). Usa PATCH para actualizaciones parciales (el cliente envía solo los campos modificados). PATCH con JSON Merge Patch (RFC 7396) es el enfoque más simple: envía un objeto JSON con solo los campos a actualizar, y null para eliminar un campo.
Basada en Keyset
GET /api/users?after_id=123&limit=20
Usa el ID del último elemento (u otro campo ordenado) para obtener la siguiente página. Similar a la basada en cursor pero con parámetros transparentes.
Recomendación: Usa basada en cursor para feeds en tiempo real y conjuntos de datos grandes. Usa basada en offset para paneles de administración donde importa saltar entre páginas.
Basado en Header
GET /api/users
Accept: application/vnd.myapi.v2+json
Ventaja: URLs limpias. Desventaja: Más difícil de probar, menos descubrible.
Parámetro de Consulta
GET /api/users?version=2
Ventaja: Fácil de probar. Desventaja: Semántica de parámetro opcional.
Recomendación: El versionado por ruta en URL es la opción más práctica. Es explícito, cacheable y funciona con todas las herramientas HTTP.
¿Debería usar la especificación JSON:API o diseñar mi propio formato?
La especificación JSON:API (jsonapi.org) proporciona un estándar integral, pero puede ser verboso para APIs simples. Para la mayoría de los proyectos, diseñar un formato personalizado más simple siguiendo los patrones de esta guía es más práctico. Usa JSON:API si necesitas bibliotecas de cliente automáticas y un estándar estricto.
Recursos Relacionados
- JSON Formatter — Formatea respuestas API
- JSON API Design Patterns — Guía completa de diseño de APIs
- JSON Schema Validation — Valida estructuras de respuesta
🛠️ Pruébalo ahora: JSON Formatter | JSON Validator — 100% gratis, todo se procesa en tu navegador. Sin subir datos.