En muchos proyectos pasa lo mismo: las reglas de negocio cambian, pero la API no está en capacidad de cambiar. O aún peor, se hacen cambios de forma forzada y desordenada. Al final se rompen integraciones, generando deuda técnica y desconfianza. El problema suele ser arquitectónico (en la etapa de diseño) y no tecnológico (en la etapa de desarrollo e implementación).
El Diseño de APIs que sobrevivan a cambios de negocio no debe interprertarse como un intento absurdo de adivinar el futuro, sino como la aceptación de que el cambio es inevitable y por lo tanto, es necesario construir con esa premisa.
1. Diseñar desde el dominio, no desde la base de datos
Un error común es exponer directamente la estructura de tablas. En el momento en que el modelo cambia, la API colapsa.
Un enfoque más robusto es aplicar principios de Domain-Driven Design (DDD). En este sentido, la API debería representar capacidades y reglas del negocio en lugar de entidades físicas de almacenamiento. Es decir, si el negocio habla de “orden”, “cliente”, “agenda” o “suscripción”, la API debe hablar ese mismo lenguaje, mientras que se mantiene la base de datos como un detalle de implementación. De esta forma, cuando el contrato refleja el dominio y no el esquema físico, se reduce la posiblidad de que los cambios internos afecten a los consumidores de la API.
2. Separar el contrato de la implementación
Una API ante todo es un contrato. Y un contrato no puede cambiar arbitrariamente. Deben tenerse buenas prácticas:
- Versionamiento explícito (/v1/, /v2/ o versionado por header).
- Política clara de descontinuación (retiro progresivo y planificado).
- No eliminar campos sin transición.
- No introducir cambios que rompan integraciones existentes sin avisar a los consumidores de la API.
Una API bien diseñada permite la evolución interna, mientras mantiene estabilidad externa. Es muy importante porque la estabilidad es un activo reputacional.
3. Diseñar para extensión y no para modificación
Un principio práctico es agregar sin romper.
- Preferir campos opcionales en lugar de obligatorios cuando sea viable.
- Usar estructuras extensibles (por ejemplo, objetos anidados en vez de listas rígidas).
- Evitar enums cerrados si el negocio es posible que los amplíe.
- Asumir que la cantidad de estados puede cambiar si el negocio lo requiere.
4. Pensar en consumidores desconocidos
Un error conceptual frecuente es diseñar la API para el frontend actual, pero el riesgo es que eso la convierte en una API acoplada.
Si la API se diseña bien:
- No depende de un cliente específico.
- No está optimizada exclusivamente para una vista.
- No mezcla reglas de presentación con reglas de negocio.
Integraciones futuras con clientes diferentes (marketplace, una app móvil o un tercero) deben ser soportadas por la API sin tener que rediseñarse por completo.
5. Controlar el crecimiento de la complejidad
Si la API quiere sobrevivir a cambios, requiere crecer con control, y para eso se deben tomar algunas decisiones estratégicas:
- Introducir patrones como CQRS cuando el dominio lo exige (separar las operaciones que modifican el estado de las operaciones que leen datos).
- Usar eventos de dominio si el negocio tiene procesos asíncronos.
- Separar servicios cuando los contextos comienzan a tener reglas diferentes.
- No todo requiere microservicios. Dividir prematuramente suele generar más fricción que valor.
6. Documentación como herramienta estratégica
Una API que no está documentada es frágil.
OpenAPI, ejemplos reales de uso y políticas de versionamiento no son “extras”, son mecanismos de gobernanza.
La documentación reduce la probabilidad de uso indebido y facilita migraciones cuando el negocio evoluciona.