APIs REST: Diseño y Mejores Prácticas

Principios de una Buena API REST

Una API bien diseñada es fácil de usar, predecible y mantenible. Estas son las mejores prácticas que todo desarrollador debe seguir.

Nomenclatura de Endpoints

# ✅ Correcto — Sustantivos en plural
GET    /api/usuarios          # Listar
POST   /api/usuarios          # Crear
GET    /api/usuarios/123      # Obtener uno
PUT    /api/usuarios/123      # Actualizar
DELETE /api/usuarios/123      # Eliminar

# ❌ Incorrecto
GET    /api/getUsuarios
POST   /api/crearUsuario
PUT    /api/updateUsuario/123

Códigos de Estado HTTP

Código	Significado	Uso
200	OK	GET, PUT exitoso
201	Created	POST exitoso
204	No Content	DELETE exitoso
400	Bad Request	Datos inválidos
401	Unauthorized	No autenticado
403	Forbidden	Sin permisos
404	Not Found	Recurso no existe
500	Server Error	Error del servidor

Versionado

/api/v1/usuarios
/api/v2/usuarios

Paginación

GET /api/usuarios?page=2&limit=20

# Respuesta
{
    "data": [...],
    "meta": {
        "page": 2,
        "limit": 20,
        "total": 150,
        "total_pages": 8
    }
}

Conclusión

Una API bien diseñada es la base de cualquier sistema moderno. Sigue estas convenciones y tus APIs serán profesionales y fáciles de consumir.