Muchas APIs se diseñan como simples conjuntos de endpoints: reciben datos, ejecutan lógica y devuelven una respuesta.
Este enfoque puede funcionar en escenarios simples, pero en sistemas reales —facturación, integraciones con terceros, automatización de procesos o flujos asíncronos— se queda corto y genera problemas estructurales.
El problema no es la API, es el diseño del sistema
Una API no debería ser un conjunto de funciones expuestas. Debería ser la puerta de entrada a un proceso bien definido.
Cuando esto no se tiene en cuenta, empiezan a aparecer problemas difíciles de detectar y aún más difíciles de corregir.
Errores habituales en el diseño de APIs
- No considerar la idempotencia de las operaciones
- Ausencia de trazabilidad (no saber qué ha ocurrido realmente)
- Falta de control de estados
- No permitir reprocesar operaciones fallidas
- Dependencia total del orden de ejecución
Estos errores no suelen aparecer en el desarrollo inicial, pero sí en producción, cuando el sistema empieza a crecer o a integrarse con otros.
Consecuencias en sistemas reales
Cuando una API no está bien diseñada, el sistema se vuelve frágil:
- Errores difíciles de reproducir
- Duplicidad de operaciones
- Inconsistencias en los datos
- Procesos que fallan sin posibilidad de recuperación
En entornos donde hay integraciones externas o procesos críticos, esto se convierte en un problema operativo serio.
Un enfoque diferente: APIs orientadas a proceso
En lugar de diseñar endpoints aislados, en Intercyd trabajamos con un enfoque distinto: cada API representa la entrada a un proceso completo.
Esto implica que cada llamada:
- Se registra (input y output)
- Tiene un estado definido
- Puede ser reprocesada si es necesario
- Es auditable en todo momento
La API deja de ser un punto de ejecución y pasa a ser un componente dentro de un sistema más amplio.
Idempotencia y control de duplicidades
Uno de los aspectos clave es la idempotencia: garantizar que una operación pueda ejecutarse varias veces sin generar efectos secundarios.
Esto es especialmente importante cuando:
- Existen reintentos automáticos
- Hay integraciones con sistemas externos
- El sistema no controla completamente el flujo de llamadas
Sin idempotencia, cualquier fallo puede provocar inconsistencias difíciles de corregir.
Persistencia del proceso en base de datos
Otro punto clave es que el proceso no vive en el código de la API, sino en la base de datos.
Esto permite:
- Registrar cada paso del proceso
- Controlar estados intermedios
- Permitir reprocesamiento
- Auditar el sistema completo
De nuevo, PostgreSQL actúa como núcleo del sistema, no como simple almacenamiento.
Simplicidad bien entendida
Este enfoque no requiere necesariamente arquitecturas complejas.
En muchos proyectos utilizamos una combinación de:
- PHP nativo
- Nginx (routing y control de acceso)
- PostgreSQL (lógica y persistencia)
La clave no está en el stack, sino en cómo se diseña el sistema.
Cuándo este enfoque marca la diferencia
Este modelo es especialmente útil cuando:
- Existen integraciones con terceros
- Hay procesos críticos (facturación, pagos, altas, etc.)
- Se requiere trazabilidad completa
- El sistema debe ser resiliente a fallos
Conclusión
Una API no debería limitarse a ejecutar código. Debería formar parte de un sistema diseñado para ser predecible, auditable y resistente.
El verdadero valor no está en los endpoints, sino en el diseño del proceso que hay detrás.