Modernización de sistemas
Diseño de API para integrar sistemas: contrato de estado actual o de eventos antes del primer adaptador
Para integrar un sistema heredado con otro sistema interno, proponemos un contrato REST de estado actual como opción por defecto; los eventos solo con una razón nombrada. Esta guía da los pasos, los responsables y la evidencia para decidir antes del primer adaptador.

La decisión antes del primer adaptador
Cuando usted integra un sistema heredado con otro sistema interno, proponemos que el contrato de API exponga el estado actual como recursos REST, salvo que exista una razón escrita de auditabilidad o reconstrucción histórica que justifique un contrato de eventos. Proponemos también que la semántica del heredado se traduzca en una capa anticorrupción en lugar de entrar al contrato.
La decisión se toma antes de escribir el primer adaptador porque, como criterio de riesgo que le sugerimos validar con su equipo, corregir un contrato con consumidores activos cuesta más que decidirlo bien al inicio.
Esta guía es para el gerente general, el director de tecnología o el director de finanzas que aprueba la integración. No asumimos que su sistema heredado tenga un defecto ni que estos patrones describan sus sistemas: son documentación internacional de arquitectura, no una descripción de lo que usted tiene. Le damos un método de diligencia, con responsables y evidencia, para que la decisión quede documentada y reversible.
Qué exige un contrato de estado actual
La guía de diseño de API web RESTful del Centro de arquitectura de Azure, en Microsoft Learn, describe una API RESTful como una interfaz sin estado y débilmente acoplada entre un cliente y un servicio. Para lograrlo, la API usa HTTP como protocolo estándar, proporciona documentación clara y admite un formato conocido de intercambio de datos, como JSON o XML. El cliente no necesita conocer la implementación interna del servicio, y el servicio no necesita conocer la del cliente.
Esa misma guía indica que las API REST se diseñan en torno a recursos, cada uno identificado por un URI único, y que la interfaz uniforme incluye los verbos HTTP estándar: GET, POST, PUT, PATCH y DELETE. El modelo de solicitud sin estado admite alta escalabilidad porque no requiere afinidad entre clientes y servidores específicos, aunque la guía también advierte que puede limitar la escalabilidad por los desafíos del almacenamiento back-end.
Una advertencia práctica: la porción de la guía de Microsoft Learn que revisamos cubre recursos, interfaz uniforme, modelo sin estado e hipermedia. No cubre reglas concretas de códigos de estado ni de versionado. Le proponemos tratar esos dos puntos como preguntas de diligencia con su equipo de ingeniería, no como decisiones ya resueltas por la guía.
Cuándo un contrato de eventos se justifica
El patrón Event Sourcing de Microsoft Learn plantea la alternativa: en lugar de almacenar solo el estado actual, se guarda la serie completa de acciones sobre un objeto en un almacén de solo anexión, que actúa como sistema de registro. El documento señala que este enfoque puede mejorar la auditabilidad y el rendimiento de escritura en sistemas complejos.
La misma documentación es explícita sobre el costo. Event Sourcing es un patrón complejo, migrar hacia él o desde él es costoso, y después de adoptarlo restringe las decisiones de diseño futuras en las partes del sistema que lo usan. La recomendación del documento es adoptarlo solo cuando ventajas como la auditabilidad y la reconstrucción histórica justifican la complejidad, y afirma que la administración de datos tradicional es suficiente para la mayoría de los sistemas y la mayoría de sus partes.
Nuestra propuesta, como paso de diligencia: el contrato de estado actual es la opción por defecto para una integración interna. Si alguien propone eventos, exija una razón nombrada por escrito, auditabilidad o reconstrucción histórica, y una comparación honesta contra esa advertencia de costo y restricción de diseño. El contexto del patrón también describe cuándo el modelo tradicional de CRUD sufre: contención de escritura bajo alta carga y pérdida de historial si no hay un mecanismo de auditoría separado. Si su caso no presenta esos dos síntomas, la razón nombrada probablemente no existe.
Qué se queda fuera del contrato
El patrón Anti-Corruption Layer de Microsoft Learn responde a un problema concreto: la mayoría de las aplicaciones dependen de otros sistemas, y los sistemas heredados suelen tener esquemas de datos enredados o API obsoletas. El documento advierte que, cuando esas características heredadas presentan problemas de calidad, el soporte afecta de forma negativa lo que podría ser una aplicación moderna con diseño limpio. La solución que describe es una capa de fachada o adaptador entre subsistemas que no comparten la misma semántica, que traduce las solicitudes de uno al otro.
De ahí sigue una inferencia nuestra, no una conclusión del documento: si su API nueva expone directamente los campos y estados del heredado, sus consumidores quedan acoplados a esa semántica, y cada capricho del sistema viejo se vuelve parte de su contrato. La capa anticorrupción evita ese acoplamiento, pero el mismo documento enumera sus costos: agrega latencia a las llamadas y agrega un servicio adicional que debe administrarse y mantenerse, y pide considerar cómo escalarla. Tenga presente la diferencia entre los dos costos: la latencia y el mantenimiento de la capa son operativos y recurrentes, se pagan mientras la capa exista; el acoplamiento, si lo acepta, se paga en cada cambio futuro del contrato. Ninguno de los dos es un pago único.
Cómo encaja la migración incremental
Si esta API es el primer paso de una modernización, el patrón Strangler Fig de Microsoft Learn marca el camino: migrar de forma incremental, reemplazando partes específicas de la funcionalidad por nuevas aplicaciones y servicios, con una fachada que enruta las solicitudes entre el sistema heredado y el nuevo. Los clientes siguen usando la misma interfaz y no saben que hay una migración en curso.
Martin Fowler, en su artículo Strangler Fig publicado el 22 de agosto de 2024 como revisión del texto de 2004, explica por qué el reemplazo total suele fallar: según su observación, ese plan aparentemente simple se ha venido abajo la mayoría de las veces, porque reemplazar un sistema serio toma mucho tiempo, los usuarios no pueden esperar nuevas funciones y es difícil especificar el comportamiento existente. Su alternativa preferida es un proceso gradual, con cuatro actividades: entender los resultados deseados, decidir cómo dividir el problema en partes, entregar las partes y cambiar la organización para sostenerlo. Fowler también advierte que los sistemas heredados rara vez tienen componentes que se puedan reemplazar de forma independiente, y que hace falta trabajo para encontrar las costuras.
El método de diligencia, paso por paso
Le proponemos este método; es una propuesta de Atom Panamá, no un estándar de los documentos citados.
Paso uno: inventariar consumidores y recursos. Responsable: el dueño del negocio de la integración, con el líder técnico. Evidencia: una lista de cada consumidor, con los campos que lee y escribe, y el recurso del heredado de donde salen.
Paso dos: clasificar cada campo, estado y error del heredado como parte del contrato nuevo o como responsabilidad de traducción de la capa anticorrupción. Responsable: el arquitecto o ingeniero líder. Evidencia: una tabla de clasificación que el dueño del negocio aprueba.
Paso tres: exigir la razón nombrada si el contrato será de eventos. Responsable: quien patrocina la integración. Evidencia: un párrafo escrito que responda a las advertencias del documento de Event Sourcing sobre complejidad, costo de migración y restricción de diseño.
Paso cuatro: definir la evidencia de reversión del primer adaptador. Responsable: ingeniería. Evidencia: una prueba de que el adaptador se puede retirar o revertir sin perder datos, ejecutada antes de aprobar el segundo adaptador.
Paso cinco: verificar que el contrato puede evolucionar sin obligar a los consumidores a conocer la estructura interna del heredado. Evidencia: un cambio de contrato de prueba, documentado, donde solo la capa de traducción se modifica.
Cuándo cambia el enfoque y cuándo traer a un ingeniero
Tres riesgos cambian la decisión. Primero, si el inventario revela contención de escritura real y una necesidad de auditoría que hoy no existe, el contrato de eventos pasa de descartado a candidato, siempre con la razón nombrada. Segundo, si los dos sistemas comparten semántica y no hay traducción que hacer, la capa anticorrupción puede ser innecesaria: pagar su latencia y su mantenimiento recurrente sin necesidad es un costo muerto. Tercero, si nadie en su equipo puede nombrar a los consumidores del sistema heredado, el problema no es el contrato sino el desconocimiento del sistema, y ningún patrón lo resuelve.
Traiga a un ingeniero cuando el paso dos requiera leer código del heredado que nadie domina, cuando no exista la evidencia de reversión del paso cuatro, o cuando la clasificación de campos no pueda completarse con la gente que tiene hoy. Ese es el momento de una evaluación de alcance fijo sobre la ruta de software en cuestión, con un informe para decidir, no para improvisar.
Lista de verificación
- Liste cada consumidor de la integración y los campos que lee y escribe.
- Clasifique cada campo, estado y error del heredado como contrato o como traducción.
- Exija la razón nombrada por escrito si el contrato será de eventos.
- Pida la prueba de reversión del primer adaptador antes de aprobar el segundo.
- Verifique que un cambio de contrato no obligue a los consumidores a conocer el heredado.
- Pregunte quién administra y escala la capa anticorrupción, y con qué presupuesto recurrente.
Preguntas frecuentes
¿Basta con exponer la base de datos del sistema heredado como API?
No como contrato. Si los consumidores ven los campos y estados del heredado tal cual, quedan acoplados a esa semántica, según la inferencia que se sigue del patrón Anti-Corruption Layer de Microsoft Learn. La traducción pertenece a una capa separada, asumiendo su latencia y su mantenimiento recurrente.
¿Qué evidencia debo exigir antes de aprobar el primer adaptador?
El inventario de consumidores con sus campos, la tabla de clasificación entre contrato y traducción, la razón nombrada si el contrato es de eventos, y la prueba de reversión del adaptador. Sin esas cuatro piezas, la decisión no está documentada.
¿Los códigos de error y el versionado se deciden con esta guía?
No aquí. La porción de la guía de Microsoft Learn que revisamos no cubre esas secciones. Trátelos como preguntas de diligencia con su equipo de ingeniería antes de firmar el contrato.