Llevo tiempo viendo el mismo error en proyectos.
Se diseña una API REST que funciona perfectamente en local. En producción, con usuarios reales, empieza a dar problemas que nadie sabe explicar.
Casi siempre es lo mismo: Error 1 — Verbos HTTP usados al tuntún El verbo HTTP no es decorativo. Hay equipos que usan POST para absolutamente todo — crear, actualizar, borrar, consultar. El resultado es una API que nadie puede entender sin leer el código por dentro.
GET es para leer. POST para crear. PUT o PATCH para actualizar — PUT reemplaza todo el recurso, PATCH solo lo que cambias. DELETE para borrar. Cuando cada endpoint hace lo que su verbo promete, la API se documenta casi sola.
Error 2 — Códigos de respuesta genéricos Devolver siempre 200 aunque algo haya fallado, o un 500 genérico para cualquier error, es uno de los problemas que más tiempo cuesta debugear en producción.
Un 401 significa que no estás autenticado. Un 403 que estás autenticado pero no tienes permiso. Un 404 que el recurso no existe. Un 422 que los datos que mandaste son inválidos. Cada código tiene un significado concreto. Usarlos bien hace que el frontend sepa exactamente qué pasó sin necesitar logs adicionales.
Error 3 — No versionar desde el principio El endpoint /api/users funciona hoy. Dentro de 6 meses necesitas cambiar la estructura de respuesta — pero ya tienes clientes usando esa versión. Sin versionado, cualquier cambio rompe algo.
/api/v1/users desde el primer día te da libertad para evolucionar sin romper lo que ya funciona.
Error 4 — Exponer más datos de los necesarios Devolver el objeto completo de la base de datos en cada respuesta es cómodo de programar y peligroso en producción. Expones campos internos, datos sensibles y estructura de base de datos que no debería salir nunca de tu servidor.
Cada endpoint devuelve exactamente lo que el cliente necesita — nada más.
Lo que tienen en común estos errores: todos se ven pequeños al principio y se convierten en problemas grandes cuando el proyecto escala.
- ¿Con cuál de estos te has encontrado más en proyectos reales?
- ¿Hay algún error de diseño de API que añadirías a la lista?
- ¿Documentas tus APIs desde el principio o cuando ya es tarde?