Buenas prácticas en el diseño de APIs REST

Diseñar una API REST de calidad va mucho más allá de simplemente exponer endpoints. Una buena API es predecible, consistente, segura y fácil de consumir. Aquí te presento las prácticas más importantes.

1. Usa sustantivos, no verbos en las rutas

El método HTTP ya describe la acción. Las rutas deben representar recursos:

❌ GET /getUsers
❌ POST /createUser
❌ DELETE /deleteUser/1

✅ GET    /users
✅ POST   /users
✅ DELETE /users/1

2. Usa los métodos HTTP correctamente

• GET – leer recursos (sin efectos secundarios)
• POST – crear un nuevo recurso
• PUT – reemplazar un recurso completo
• PATCH – actualizar parcialmente un recurso
• DELETE – eliminar un recurso

3. Versiona tu API desde el principio

/api/v1/users
/api/v2/users

Versionar evita romper clientes existentes cuando evoluciona tu API.

4. Usa códigos de estado HTTP correctamente

200 OK              → solicitud exitosa
201 Created         → recurso creado
204 No Content      → éxito sin cuerpo de respuesta
400 Bad Request     → datos inválidos del cliente
401 Unauthorized    → no autenticado
403 Forbidden       → autenticado pero sin permiso
404 Not Found       → recurso no existe
422 Unprocessable   → validación fallida
500 Server Error    → error interno del servidor

5. Estructura de respuesta consistente

Nunca cambies el formato de respuesta entre endpoints. Usa una estructura estándar:

// Éxito
{
  "data": { "id": 1, "name": "Ana" },
  "meta": { "page": 1, "total": 100 }
}

// Error
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "El campo email es requerido.",
    "details": [{ "field": "email", "issue": "required" }]
  }
}

6. Paginación, filtros y ordenamiento

GET /users?page=2&limit=20
GET /users?sort=createdAt&order=desc
GET /users?role=admin&status=active

7. Seguridad básica

• Siempre usa HTTPS en producción
• Implementa autenticación con JWT o OAuth 2.0
• Valida y sanitiza todos los inputs
• Implementa rate limiting para evitar abusos
• Usa headers de seguridad: CORS, Content-Security-Policy

8. Documenta tu API

Una API sin documentación es una API que nadie usará. Herramientas como Swagger/OpenAPI o Postman te permiten generar documentación interactiva de forma sencilla.

9. Nombrado en plural y minúsculas

✅ /api/v1/blog-posts
✅ /api/v1/users/1/orders
❌ /api/v1/BlogPost
❌ /api/v1/User/1/Order

10. Idempotencia

Las operaciones GET, PUT y DELETE deben ser idempotentes: llamarlas múltiples veces debe tener el mismo efecto que llamarlas una sola vez.