La historia de la API REST que no quiso ser olvidada

5 aprendizajes que te llevas de este episodio:

Importancia de la refactorización y aprendizaje a través del error en la programación.
Aplicación de buenas prácticas y principios SOLID para crear APIs robustas.
Separación de responsabilidades para lograr un código modular y mantenible.
Transformación de obstáculos en oportunidades de mejora continua y creatividad.
Evolución del desarrollo artesanal a partir de la experiencia práctica y reflexiva.

La artesanía del software: redescubriendo la claridad en la programación ¶

El código es una conversación íntima entre el programador y la máquina. No basta con saber cómo funciona la tecnología; es preciso dominarla a través de la experimentación, el error y la reinvención constante de nuestras prácticas. La experiencia y el placer de refactorizar un proyecto, incluso cuando se desborda y se transforma en algo mayor a lo esperado, revelan verdades sobre nuestra forma de abordar el desarrollo. La práctica arraiga el conocimiento y nos enseña que cada línea de código es un ensayo de nuestras ideas, susceptible de mejora constante.

Aprendiendo a través de la práctica y el error ¶

En la creación de una REST API con PHP, la experiencia no se limita a plasmar un conjunto de instrucciones en un archivo. Es una búsqueda de claridad, una oportunidad para identificar y separar las responsabilidades. Al iniciar un proyecto con un script de PHP puro, el reto consiste en transformar un simple enunciado en una arquitectura que responda a peticiones HTTP con precisión. El recorrido desde una primera versión desbordada, con “switches horrendos” y definiciones enredadas, hasta un sistema segmentado que respeta principios como la responsabilidad única, es una clara demostración de cómo se esculpe el código.

El proceso de refactorización se asemeja a trabajar en una obra de artesanía: desmontar, limpiar, reordenar y volver a ensamblar cada componente para que tenga sentido en el conjunto. Durante este trayecto se resulta inevitable preguntarse: ¿por qué no bajar al barro, sumergirse de lleno en la estructura del código? Esa intuición, la de reiniciar la interacción con la máquina y configurar cada elemento con intención, abre puertas a mejorar tanto la legibilidad como la mantenibilidad del software.

El acto de escribir y reescribir transforma el pensamiento. Cada reorganización del código, cada cambio en la forma de gestionar rutas, controladores y respuestas digitales, expone áreas de mejora y fortalece la disciplina de pensar en cada línea. Es en ese proceso donde la refactorización se vuelve un acto de descubrimiento personal y profesional, permitiéndonos capturar la esencia de la programación y, a veces, hasta sorprendernos con ideas que no habíamos considerado inicialmente.

El papel de las buenas prácticas y la refactorización ¶

Durante este recorrido, es habitual encontrarse con la necesidad de tomar decisiones difíciles y, a veces, poco convencionales. La transición de un código inicial que surge de la práctica “a lo chusco” a una solución que respeta ciertos principios de diseño revela la importancia de las buenas prácticas. Separar las responsabilidades no es simplemente modularizar el código: es distinguir entre la lógica que capta una petición, la que la procesa y la que la devuelve.

Entre las lecciones más valiosas se encuentran:

Identificar y separar la lógica de negocio de la representación de datos.
Aplicar los principios SOLID para evitar el código acoplado y los God Objects.
Adoptar un tipado que obligue a que los datos sean del tipo esperado, minimizando errores inesperados.
Manejar las excepciones de forma que tanto el desarrollador como el cliente reciban información útil acerca de lo sucedido.
Emplear técnicas de inyección de dependencias para mantener la flexibilidad y la reutilización del código.

El proceso de refactorización permite que elementos como el mapeo de rutas a controladores y la separación entre la petición y la respuesta tomen forma clara. Así, la API se convierte no en una mera colección de instrucciones, sino en un sistema en el que cada componente cumple una función explícita y definida.

La importancia de la separación de responsabilidades ¶

Uno de los retos abordados fue la tendencia a dejar que un único bloque de código se encargara de tareas múltiples. En lugar de permitir que un switch se encargue de determinar rutas, controlar peticiones y emitir respuestas, se optó por separar cada responsabilidad en módulos distintos. Esto no solo clarifica la intención del código, sino que también permite que cada bloque evolucione de manera independiente sin contaminar al resto del sistema.

Por ejemplo, el controlador que mapea las rutas a una lógica de negocio debe ocupar el rol exclusivo de interpretar las solicitudes HTTP y transformar esa información en respuestas estructuradas. Así, al separar:

La definición de rutas (URI y verbos HTTP).
La lógica de procesamiento (controladores y validaciones).
El manejo de respuestas (formateo y asignación de códigos HTTP).

se crea un ambiente en el que cada parte es fácilmente testeable y susceptible de mejoras aisladas. Esa disciplina de separar y encapsular conceptos es, en esencia, el valor de la artesanía en el software.

Además, el manejo de errores se transforma en una práctica consciente. Saber comunicar los fallos a través de códigos HTTP adecuados (200 para éxito, 404 para recursos no encontrados, 500 para errores fatales) es fundamental. Es parte de ese compromiso para que el software se comporte de manera comprensible, tanto para los desarrolladores que lo mantienen como para los clientes que lo consumen.

El balance entre optimismo y pragmatismo ¶

En el vertiginoso mundo de la programación, impulsar el optimismo es tentador. Ante la inmensidad de herramientas y frameworks que pretenden facilitar el desarrollo, uno cae en la trampa de creer que basta con utilizar algo “opinionated” para asegurar el éxito de nuestro proyecto. Sin embargo, esa comodidad suele ocultar el riesgo de abandonar el análisis profundo de cada decisión.

El proceso de refactorización demostró que la magia de aprender no radica en seguir patrones prefabricados, sino en retomar el control del proyecto. Es posible disfrutar organizando el código, armando estructuras coherentes y, sobre todo, entendiendo a fondo cada elección técnica. La evolución progresiva, desde una REST API concebida en un ejercicio práctico hasta una aplicación con principios claros y separaciones precisas, es una invitación a la humildad frente a la invención.

Como se expresó en un momento apasionante del proyecto:

“Oí una voz, o escuché una voz. Soy el framework que deseas. Te haré enrutado igual que te plancharé la ropa.”

Esta cita, tomada sin cambios de una sesión de inspiración, ilustra la dualidad entre la seducción de la inmediatez que ofrece un framework y la determinación de rehacer cada paso a partir de la reflexión y el análisis profundo. No se trata de seguir ciegamente un camino ya pavimentado, sino de elegir conscientemente la ruta que mejor se adapta a nuestras necesidades y conocimientos.

Riesgos y fallos en la construcción de APIs ¶

El desarrollo de una REST API práctica expone numerosos riesgos: el tipado débil de PHP, la tentación de mezclar responsabilidades y la dificultad de prever errores que se manifiestan en puntos críticos. Prevenir, en este contexto, es aceptar que el fallo es inminente y, por ello, prepararse para enfrentarlo.

Entre las estrategias que se volvieron indispensables se encuentran:

El uso proactivo de excepciones para captar errores en momentos tempranos.
La asignación correcta de códigos HTTP para comunicar el estado de la respuesta.
La configuración de modelos y validaciones que aseguren que los datos entrantes cumplen con los formatos esperados.
La inyección de dependencias para reducir el acoplamiento entre componentes.
La simplificación de la lógica al eliminar dependencias que no aporten al entendimiento del flujo.

Estos principios no solo promueven un código más limpio; también refuerzan el compromiso del programador con la estabilidad y la claridad operativa. Al adoptar este enfoque, se crea un ambiente en el que la evolución del sistema es predecible y cada error, por más inevitable que parezca, se convierte en una oportunidad para aprender y mejorar.

El valor de escribir código a mano ¶

Escribir el código a mano es un ejercicio de claridad mental. Te obliga a definir con precisión cada paso del proceso y a enfrentarte, de manera directa, con las imperfecciones de tu propio pensamiento. Al construir una API desde cero, el reto es tan importante como el resultado final: es una oportunidad de comprender verdaderamente lo que sucede entre la entrada y la salida de datos.

Las siguientes ideas estructuran ese proceso:

La interacción con la tecnología debe ser un acto consciente. Resiste la tentación de automatizar todo sin comprender cada engranaje.
La refactorización implica despojarse de la comodidad y adentrarse en el análisis de cada decisión técnica.
La creación de un código robusto se fundamenta en la disciplina de separar la lógica, validar datos y gestionar errores de manera meticulosa.
La pasión por el detalle se refleja en la búsqueda constante de mejorar, sin importar lo funcional que el primer intento haya sido.

El ejercicio de construir algo tangible, como la REST API para un sistema de control de gastos, permite experimentar de primera mano lo que significa “programar bien”. Cada línea revisada y cada error gestionado no solo mejoran el sistema, sino que también refinan nuestra propia capacidad para pensar y crear.

Principios que definen el camino ¶

La artesanía del software se basa en principios que deben servir de guía en cada proyecto. Entre ellos, se destacan:

Responsabilidad única: Cada componente debe tener un propósito claro y definido.
Inyección de dependencias: Permite que los distintos módulos se integren sin acoplamientos innecesarios.
Validación y tipado de datos: Garantiza que el sistema es coherente y predecible en su comportamiento.
Gestión cuidadosa de errores: Transforma los fallos en oportunidades de aprendizaje y reajuste.

Adoptar estas prácticas exige un compromiso continuo con el crecimiento personal y profesional. No se trata de implementar una lista de “buenas prácticas” por cumplir, sino de comprender el porqué y el cómo detrás de cada decisión. Es en esa intersección donde la creatividad y la disciplina encuentran su máxima expresión.

Transformar problemas en oportunidades ¶

El desarrollo de software raramente es una línea recta. Los obstáculos se convierten en lecciones, y cada error, por más pequeño que sea, encierra una enseñanza. La clave está en transformar las dificultades en oportunidades para profundizar en el conocimiento y reajustar la dirección del proyecto.

En este sentido, el proceso de refactorización no es solo una cuestión técnica, sino también un ejercicio de humildad y resiliencia. Se reconoce que la primera solución nunca es perfecta y que la verdadera maestría reside en la capacidad de iterar, examinar y mejorar continuamente. El paradigma del “fallar pronto” se convierte en una bandera para quien decide enfrentar el código con honestidad, dispuesto a reconocer sus limitaciones y a trabajar para superarlas.

Cada componente revisado y cada error capturado se suman a una experiencia invaluable, forjando un camino hacia un software más sólido y una práctica de programación más consciente. No es raro encontrarse con desafíos inesperados, desde la incorrecta asignación de tipos hasta el acoplamiento excesivo en los controladores. Sin embargo, es precisamente en esos momentos donde se fortalece la capacidad de prever y manejar las complejidades inherentes al desarrollo.

La síntesis de la experiencia ¶

La travesía de transformar un proyecto caótico en una estructura bien definida es, en definitiva, un ejercicio de autoconocimiento y madurez profesional. Cada decisión, cada separación y cada validación forman parte de un todo que busca no solo la funcionalidad, sino la elegancia en la solución. La experiencia de escribir código de principio a fin enseña que el valor real radica en la capacidad de aprender del error y de adaptar nuestras herramientas a las exigencias reales del proyecto.

Adoptar un estilo artesanal en el software implica resistir la tentación de dejarse llevar únicamente por la inmediatez que ofrecen los frameworks y herramientas modernas. Es, en cambio, un compromiso con la precisión, con la claridad en la comunicación interna del sistema y, sobre todo, con la búsqueda de soluciones que convivan en armonía con la lógica humana.

El desarrollo de una REST API no es simplemente una práctica técnica, sino una metáfora del camino que transita el programador: una senda de constante reexaminación, de corrección de errores y de validación incesante de cada idea, principio y línea de código.

Invitación a la reflexión ¶

En cada proyecto, por pequeño que parezca, se esconde la oportunidad de aprender y crecer. Es en el detalle del manejo de rutas, en la separación de responsabilidades y en la gestión meticulosa de errores donde se revela la verdadera esencia de la programación. Esa práctica, a veces frustrante y tediosa, es la que al final produce una obra de la que uno puede sentirse orgulloso.

Y es que escribir código es, en última instancia, un acto de artesanía. Como la tinta en el papel, cada instrucción es un reflejo de la mente del programador, una declaración de intenciones y una invitación a seguir aprendiendo. La diferencia está en reconocer que cada error es un maestro y que la belleza del software se halla en la claridad con que comunicamos nuestras ideas a la máquina.

Al final, la transformación de un código desbordado y “chusco” en una API organizada y respetuosa de sus propias reglas no es solo una victoria técnica, sino también un triunfo personal. Una invitación a explorar, a experimentar y a nunca conformarse con soluciones superficiales cuando se puede aspirar a algo más profundo y elegante.

Cada decisión tomada durante el desarrollo es un paso hacia un conocimiento más profundo, y cada error superado fortalece la convicción de que en el detalle reside la diferencia. Es una lección que trasciende el ámbito de la programación para convertirse en una filosofía de la práctica y un compromiso con la excelencia.

En definitiva, la artesanía del software no es solo un conjunto de buenas prácticas, sino una forma de pensar y de actuar que transforma el código en un arte—un arte que requiere pasión, precisión y, sobre todo, una incesante disposición a aprender.

Se me fue de las manos.

Iba a ser un curso para explicar lo que es una API REST (o Rest API, o como se escriba), cuáles son las buenas prácticas a seguir para crearla y lo importantes que son los métodos y códigos HTTP.

Y luego, se desmadró.

¿Cómo iba a dejar aquello hecho de cualquier manera?

Así que preparando el código fui creciendo.

Sin darme cuenta.

Poco a poco iba extrayendo métodos, usando la programación orientada a objetos, los principios SOLID, las buenas prácticas…

Estaba disfrutando. Pasándomelo como un enano.

Y este es el resultado: Crea una API REST artesana con PHP

(El repositorio de código está disponible en abierto).

Dónde el código me lleve ¶

La historia que te cuento en este episodio es la de cómo se fue te gestando todo esto, casi sin quererlo.

La narrativa se basa en cómo la API empezó a tener vida propia y fue convirtiéndose desde un switch “mondo y lirondo” a un pequeño framework.

Todo muy mejorable, es cierto, pero este es el esquema de lo que queríamos construir:

API REST Como crear una API REST con PHP

Y aquí un fragmento del código por el que empezamos:

Este ejemplo evolucionó hasta esta estructura de código:

Otros episodios relacionados ¶

Algunos libros de referencia ¶

Comentaba durante el episodio que “flotaban” sobre mí cosas que recordaba de antiguas lecturas y estudios.

Refactoring.guru fue el primer sitio donde me interesé por la refactorización, pero no se lo recomiendo a los novatos.

Han sido claves Clean Code de Robert Martin o Extreme Programming Explained de Kent Beck.

Más específicamente los prácticos Pro PHP Refactoring o 99 Bottles of OOP de Sandi Metz.

El próximo domingo tengo claro de lo que voy a hablar en la newsletter más chispeante para developers en castellano.

Programar en el tiempo libre, ¿sí o no?

Soy defensor del “si”, pero comprendo el “no”.

Trazaremos algunas ideas para poder integrar el tiempo de trabajo en la programación por placer. Se me están ocurriendo ya…

Para recibirlo en tu bandeja de entrada solo tienes que suscribirte gratis.

¡Nos escuchamos el próximo martes!

WR 167: La historia de la API REST que no quiso ser olvidada