Pasé tres años en una empresa construyendo una API que empezó de maravilla. El primer endpoint era perfecto. Teníamos un patrón. Todos lo entendían. Entonces contratamos a dos desarrolladores más.
Uno se saltó los Resources y devolvía arrays crudos. Otro validaba en el propio controlador porque los FormRequests le parecían «demasiado abstractos». Alguien quiso DTOs en todas partes por «seguridad de tipos», y eso produjo respuestas con formas distintas. Otro envolvió Eloquent en repositorios «por si acaso cambiamos de base de datos».
Nadie se equivocaba. Cada decisión tenía sentido por separado.
Entre todos construimos una API en la que no podías leer dos endpoints y entender el tercero. Cada funcionalidad nueva empezaba con un «¿cómo lo hicimos la última vez?», y la respuesta cambiaba cada vez. Un endpoint cacheaba con agresividad. Otro no cacheaba nada. Uno devolvía códigos de estado correctos; otro enterraba los errores dentro de respuestas 200.
Al sexto mes ya no entregábamos. Leíamos nuestro propio código para averiguar qué hacía. Añadir un endpoint llevaba días cuando antes llevaba horas. Las revisiones de código se convirtieron en debates de arquitectura. Los desarrolladores junior iban más lentos porque tenían que aprender un patrón distinto para cada endpoint en lugar de uno solo.
Pull requests que debían resolverse en una hora se quedaban días sin cerrar. No porque la lógica estuviera mal, sino porque cada endpoint abría una discusión nueva. Y ninguna discusión se cerraba, porque no teníamos cimientos, solo precedentes que se contradecían.
Lo irónico es que no teníamos problemas de rendimiento ni de escala. La «arquitectura flexible» que creíamos estar construyendo se convirtió en lo más inflexible que cabe imaginar. No se podía cambiar nada, porque nadie entendía por qué estaba hecho así.
Al final reescribimos la API, no porque estuviera rota, sino porque la consistencia se había venido abajo.
La segunda vez elegimos un solo patrón. FormRequests para la validación. Resources para las respuestas. Una única estructura de error. Sin excepciones. Sin «este endpoint es especial».
Discutimos una vez, nos comprometimos y seguimos adelante.
En pocas semanas entregábamos más rápido que en el primer mes, y cada endpoint abarataba el siguiente. Cuando no tienes que pensar cómo se hace algo, te dedicas al problema de negocio que de verdad importa.
Desde entonces he aplicado el mismo enfoque en varias APIs en producción, y el resultado ha sido siempre el mismo: primero claridad, después velocidad, por último escala. La lista de comprobación tampoco ha cambiado: usa lo que Laravel ya te da, borra antes de añadir y deja que la solución sea aburrida.
Por eso existe este libro. No porque haya encontrado «la mejor manera», sino porque viví lo que pasa cuando no se decide desde el principio, y vi lo que la consistencia hace posible.