Diseñar servicios en FastAPI alrededor de transacciones de negocio y no de CRUD

Cuando las APIs CRUD dejan de funcionar

Muchas APIs internas se sienten limpias el primer día porque reflejan perfectamente la base de datos.

Crear un registro.
Actualizar un registro.
Eliminar un registro.
Devolver el modelo.

Ese enfoque es rápido de construir y fácil de probar cuando el backend solo administra datos.

El problema aparece cuando la API ya no representa una sola escritura en una tabla. En sistemas empresariales una llamada API suele significar algo distinto:

• aprobar un movimiento
• registrar un pago
• cerrar un periodo
• generar un estado de cuenta
• aplicar un descuento o una conciliación

Esas acciones representan transacciones de negocio, no operaciones CRUD.

Cuando el backend sigue modelando la API como acceso directo a tablas, la lógica termina dispersándose entre routers, modelos, jobs y condiciones específicas de UI.

El problema con APIs orientadas a tablas

Los endpoints CRUD parten de una suposición implícita: la fila de base de datos representa la unidad de intención del sistema.

En sistemas ERP o financieros eso rara vez es cierto. La unidad real es el resultado de negocio.

Por ejemplo:

Un pago solo es válido si el estado de cuenta lo permite.
Un periodo contable solo puede cerrarse bajo ciertas condiciones financieras.
Un movimiento de inventario puede afectar múltiples tablas y dominios.
Una acción comercial puede activar reglas internas de auditoría.

Cuando la API se diseña como acceso directo a tablas aparecen varios problemas.

La validación se dispersa entre capas porque ningún endpoint posee la regla completa.
Las respuestas reflejan persistencia y no significado del proceso.
Las transiciones de estado se vuelven implícitas y difíciles de explicar.

La primera versión del sistema funciona. Las siguientes empiezan a romperse bajo complejidad.

Modelar transacciones de negocio en la capa de servicio

Una capa de servicio funciona mejor cuando representa una transacción completa del dominio.

Un servicio debe encargarse de:

• validar las precondiciones del dominio
• ejecutar la transición de estado esperada
• registrar efectos colaterales importantes
• devolver una respuesta alineada al proceso de negocio

En aplicaciones FastAPI esto normalmente significa que los routers permanecen delgados.

El router:

• recibe la solicitud
• valida entrada
• invoca un servicio

El servicio:

• ejecuta el caso de uso
• coordina repositorios
• aplica reglas del dominio
• devuelve el resultado

De esta forma la política del sistema vive en una capa visible y explícita.

Estructura práctica en FastAPI

Una estructura común en backends empresariales es:

Router → recibe la solicitud HTTP
Schema → valida estructura de datos
Service → coordina el caso de uso
Repository / ORM → accede a persistencia

Esto refleja mejor cómo operación y soporte entienden el sistema.

Si un pago falla, la pregunta no es:

“¿qué update se rompió?”

La pregunta real es:

“¿qué regla bloqueó el pago y en qué estado estaba la cuenta?”

Cuando los servicios modelan casos de uso, esa respuesta es visible en código.

Las transiciones de estado deben ser explícitas

Uno de los mayores riesgos en software empresarial es fingir que las transiciones son simples updates.

Pasar de:

pendiente → aprobado
abierto → cerrado
provisional → confirmado

tiene significado operativo.

Una buena capa de servicio debe hacer explícito:

• qué estados actuales son válidos
• qué estados de destino están permitidos
• qué efectos ocurren cuando la transición se completa
• qué registros de auditoría se generan

Cuando esto es explícito, la API gana estabilidad incluso si la implementación interna cambia.

El tradeoff

Agregar una capa de servicio introduce más estructura.

En aplicaciones pequeñas esto puede parecer innecesario. En sistemas empresariales suele ser lo contrario.

El tradeoff es simple:

más diseño al inicio
menos complejidad accidental cuando el sistema crece

Cuando el backend soporta jobs, tooling administrativo, soporte operativo y consumidores externos, es importante tener un lugar donde el caso de uso se explique claramente.

Cómo cambia el diseño de APIs

Cuando las APIs representan acciones de negocio y no tablas, la superficie cambia.

Los endpoints se nombran por acciones.
La validación se vuelve contextual.
Las respuestas reflejan estado de negocio.
Los consumidores dependen de intención y no de persistencia.

Esto vuelve la API más estable frente a cambios internos.

Impacto en producción

En sistemas reales el beneficio principal es operativo.

Los incidentes se diagnostican más rápido.
Las auditorías encuentran decisiones claras.
Las pruebas pueden concentrarse en flujos críticos.

El resultado no es una API más elegante. Es un backend que puede seguir evolucionando sin convertirse en una colección de excepciones.