Integrating legacy databases with new processes via controlled data contracts
The new API returns a successful response, but the reference directory in the legacy database interprets the status, identifier, or date differently from the new process. As a result, a situation arises where the message is technically delivered, but the business operation fails or silently distorts financial reporting. To resolve this issue, an architect must go beyond simply configuring network connections and focus on the semantic interoperability of the systems.
Why technical connection does not mean data compatibility
In system integration practice, there is often an illusion that successfully establishing a network connection or agreeing on transmission formats (for example, JSON via REST) automatically solves the interaction problem. However, technically connecting systems at the network or protocol level does not mean semantic compatibility of their data. Each system has its own domain model, which has been shaped over the years under the influence of specific business requirements and the limitations of past technological generations.
When a new service attempts to interact with a legacy database directly, a conflict of interpretations arises. For example, a status field in the new system may have strict typing and transition logic, whereas in the old database it is stored as an arbitrary text string or numeric code without documentation. Attempting to map such fields directly leads to an accumulation of errors that are difficult to detect at the infrastructure monitoring level.
Limits of responsibility of the OpenAPI specification
To describe the interaction between modern services, using the OpenAPI specification has become standard practice. It defines a programming language-agnostic description of the HTTP API interface, enabling humans and computers to understand the capabilities of the service without analysing its source code. This is an effective tool for documenting a technical contract, but an architect must consider its limits.
Describing an interface using OpenAPI does not equate to a guarantee of data security or consistency. The specification can define the request structure and field types, but it cannot validate the business rules behind those fields. For example, the OpenAPI schema will confirm that the transmitted value is a number, but it does not know whether this number corresponds to the actual stock balance in the legacy system, and it will not protect against a logical conflict during parallel updates.
Isolating legacy models through an Anti-Corruption Layer
To prevent legacy semantics from penetrating new business processes, architects use the Anti-Corruption Layer (ACL) pattern. This layer isolates different models and semantics of systems through a special facade or adapter. Instead of adapting a new microservice to the limitations of an old database, the ACL translates requests from the canonical format to the legacy format and vice versa.
Designing such an adapter requires trade-offs. The Anti-Corruption Layer isolates systems, but it adds latency to message transmission and requires separate maintenance as an independent infrastructure component. At the integration boundary through the ACL, it is necessary to ensure strict data consistency control, schema validation at every step, detailed logging, and end-to-end observability for rapid localisation of translation errors.
Comparison of technical approaches to synchronisation
The choice of tool for transferring data between the legacy environment and new processes depends on the requirements for latency, data volumes, and the criticality of data loss. Below is a comparison of the main architectural approaches.
| Integration method | Data transmission mechanism | Main limitations and risks |
|---|---|---|
| API adapters (ACL) | Synchronous HTTP/gRPC requests via a translator | Increased latency, additional point of failure |
| Logical replication | Transmission of changes using the publisher/subscriber model | Conflicts during parallel writes from different sources |
| Change Data Capture (CDC) | Event pipeline via reading transaction logs | Asynchrony, complexity of pipeline configuration and monitoring |
| Event-driven exchange | Asynchronous messages in a standardised format | Lack of built-in guarantees for message delivery and ordering |
When using logical replication (for example, in PostgreSQL), changes are transmitted continuously after the initial data snapshot. However, conflicts are possible if writes from other sources enter the same tables. In turn, Debezium builds a CDC pipeline through connectors to database change logs. Events can be transmitted via Kafka Connect, Debezium Server, or the embedded Debezium Engine.
To unify the description of such events, the CloudEvents specification is often used. It standardises the way events are described for interoperability across services, platforms, and systems, with bindings to HTTP, Kafka, AMQP, and MQTT, and JSON and Avro formats. However, standardising the event format does not equate to a guarantee of message delivery, ordering, or exactly-once processing — these tasks are resolved at the transport infrastructure and handler logic levels.
Strategies for conflict control during parallel writes
When systems operate in parallel, there is a risk of simultaneous updates to the same record in the legacy database and through the interface of the new service. Since CDC processes are asynchronous, there is a time window (replication lag) during which data in the systems is inconsistent.
To minimise such risks, it is necessary to implement version control strategies (for example, optimistic locking based on timestamps or incremental counters), clearly define acceptable latency limits for the business process, and establish automated data reconciliation procedures. It is also critically necessary to ensure data lineage, which allows tracking exactly which system and at what point in time initiated the change of each specific attribute.
Building integration layers based on UnityBase
IQusion officially offers the development of custom solutions and the integration of modules with existing information systems. To build enterprise web-oriented systems, the company uses the UnityBase platform. Thanks to this approach, developers can define canonical data contracts and create flexible Anti-Corruption layers that translate legacy data structures into modern formats, minimising the risks of information integrity violation during the evolutionary modernisation of the organisation's IT landscape.
- Semantic mapping: Verify that all data types, date formats, time zones, and status codes have a clear two-way translation rule in the contract.
- Model isolation (ACL): Ensure that the new business process does not access the legacy database tables directly, but interacts exclusively through the adapter interface.
- Conflict resolution protocol: Define the system's behaviour during simultaneous data updates in the legacy environment and the new service (for example, source priority or manual resolution).
- Latency control (Latency SLA): Establish the acceptable delay time for asynchronous synchronisation and configure alerts for exceeding this limit.
- Reconciliation tools: Develop regular automated procedures for comparing checksums or record counts between systems to detect discrepancies.
Frequently Asked Questions
Can OpenAPI be used to guarantee data security during integration?
No, OpenAPI only defines a programming language-agnostic description of the HTTP API interface. It helps to understand the structure of requests and the capabilities of the service, but it is not a tool for ensuring security, data consistency, or business logic compatibility.
What are the main disadvantages of using an Anti-Corruption Layer (ACL)?
Implementing an Anti-Corruption Layer allows for reliable isolation of different data models, but this layer adds extra latency to message transmission and requires separate maintenance as an independent system component.
Does using CloudEvents guarantee message delivery?
No, the CloudEvents specification only standardises the way events are described to ensure interoperability between systems. It does not contain built-in mechanisms and does not guarantee delivery, message ordering, or exactly-once processing.
