Mejores prácticas HTTP REST

🌐 Guía Breve sobre HTTP REST

REST (Representational State Transfer) es un estilo de arquitectura para diseñar APIs basadas en el protocolo HTTP. Se basa en la interacción entre clientes y servidores mediante operaciones estándar como GET, POST, PUT, PATCH y DELETE.

Las APIs RESTful son utilizadas en la mayoría de aplicaciones web y móviles modernas debido a su simplicidad, escalabilidad y compatibilidad con distintos lenguajes de programación y plataformas.

🎯 ¿Por qué seguir buenas prácticas en REST?

El uso de buenas prácticas en el diseño de APIs REST tiene varias ventajas: ✅ Claridad y coherencia → Facilita la comprensión y el mantenimiento de la API.
✅ Eficiencia → Reduce la carga del servidor y mejora la velocidad de respuesta.
✅ Seguridad → Protege los datos y usuarios contra amenazas como inyecciones SQL o XSS.
✅ Escalabilidad → Permite que la API crezca sin comprometer el rendimiento.
✅ Interoperabilidad → Hace que la API sea más fácil de usar en diferentes plataformas y dispositivos.

🚀 Principales verbos HTTP en REST

  • GET → Obtiene recursos.
    • GET /usuarios/1
  • POST → Crea un nuevo recurso.
    • POST /usuarios
  • PUT → Actualiza un recurso existente (reemplazo completo).
    • PUT /usuarios/1
  • PATCH → Actualiza parcialmente un recurso.
    • PATCH /usuarios/1
  • DELETE → Elimina un recurso.
    • DELETE /usuarios/1

🛠 Mejores prácticas

✅ 1. Usar y responder con JSON

Todas las solicitudes y respuestas deben ser en JSON:

{
  "id": 1,
  "nombre": "Ejemplo"
}

Encabezado recomendado:

Content-Type: application/json
Accept: application/json

✅ 2. Usar sustantivos en lugar de verbos en los endpoints

❌ Incorrecto: /obtenerUsuarios
✔️ Correcto: /usuarios

✅ 3. Nombrar colecciones en plural

✔️ /usuarios, /productos, /pedidos
❌ /usuario, /producto

✅ 4. Anidar recursos para objetos jerárquicos

Si un recurso depende de otro, usa anidamiento:
✔️ GET /usuarios/1/pedidos → Obtiene los pedidos del usuario con ID 1.

✅ 5. Manejar errores adecuadamente

Usar códigos de estado HTTP estándar:

  • 200 OK → Respuesta exitosa
  • 201 Created → Recurso creado
  • 204 No Content → Operación sin respuesta
  • 400 Bad Request → Solicitud mal formada
  • 401 Unauthorized → No autenticado
  • 403 Forbidden → No autorizado
  • 404 Not Found → Recurso no encontrado
  • 500 Internal Server Error → Error del servidor

Ejemplo de respuesta de error:

{
  "error": "Usuario no encontrado",
  "codigo": 404
}

✅ 6. Permitir filtrado, ordenamiento y paginación

Ejemplo de filtrado:
✔️ /usuarios?rol=admin

Ejemplo de ordenamiento:
✔️ /usuarios?sort=nombre

Ejemplo de paginación:
✔️ /usuarios?page=2&limit=10

✅ 7. Mantener buenas prácticas de seguridad

🔒 Usar HTTPS siempre.
🔒 Autenticación con JWT, OAuth2 o API Keys.
🔒 Validar y sanitizar entradas para evitar inyecciones SQL/XSS.

✅ 8. Cachear datos para mejorar el rendimiento

Para reducir la carga del servidor, usar:
✔️ ETag
✔️ Cache-Control: max-age=3600

✅ 9. Versionar la API para cambios futuros

📌 Incluir la versión en la URL:
✔️ /v1/usuarios

📌 O en los headers:
✔️ Accept: application/vnd.miapi.v1+json

🚀 Siguiendo estas prácticas, tu API REST será más clara, escalable y segura.