API Consolidation After a System Migration

1. Background

After the interface migration, the new system served more than 1,000 interfaces inherited from the old system. The business domain did not necessarily require that many distinct interfaces. Around 200 domain-level APIs could cover the core capabilities in HR master data, including employees, departments, reporting lines, and job structures.

The next step was to consolidate redundant interfaces, guide calling systems toward the domain APIs, and establish clearer boundaries for future changes.

2. Goals

1. Consolidate more than 1,000 legacy interfaces into roughly 200 domain-level APIs.
2. Keep existing interfaces available to callers during the transition.
3. Have newly integrated systems call the domain APIs directly.
4. Retire legacy interfaces gradually when they are no longer needed.

These are the goals of the consolidation plan, rather than a claim that every old interface had already been retired.

3. Proposed Approach

Redraw Domain Boundaries

Group capabilities around the employee, department, reporting-line, and job-system domains, with separate cross-domain aggregation APIs. Classify each old interface by whether a domain API can replace it directly, whether its parameters need adaptation, or whether it combines multiple domains.

The point is to organize behavior around meaningful domain boundaries, not merely to reduce the number of endpoints.

Turn Old Interfaces into Compatibility Wrappers

During consolidation, an old interface can retain its external contract while routing work to the new domain API:

Legacy interface
  -> parameter conversion
  -> domain API
  -> execution
  -> result conversion
  -> legacy response format

The wrapper keeps parameter adaptation, response adaptation, and protocol compatibility. Core business logic moves to the domain API.

Retire Low-Traffic Interfaces Carefully

For an old interface with little or no traffic, inspect historical calls, identify its calling systems and owners, and confirm with them whether it is still used. Only then can the interface be retired. This avoids keeping every compatibility wrapper indefinitely.

4. Complex Call Paths

An extreme call path might be:

External system
  -> old interface in the old system
  -> forwarded old interface in the new system
  -> protocol layer
  -> domain API

Several forwarding and gateway layers may be involved. The stability concerns therefore resemble those of the original system migration.

5. Stability and Staged Rollout

The consolidation plan reused observability, distributed tracing, traffic analysis, and staged-rollout components from the interface migration. The migration addressed which system served a call; consolidation addressed which interface held the domain behavior. The rollout and communication with calling teams followed a similar process.

6. Main Difficulties

The difficult parts were drawing useful domain boundaries and coordinating with upstream systems. The effort was comparable to the migration work, with much of its cost in understanding business behavior and managing dependencies rather than implementing low-level infrastructure.

7. Summary

This plan built on the completed system migration. It proposed domain APIs, compatibility wrappers for old contracts, and gradual retirement of unused interfaces. Staged rollout and communication would let the interface model evolve without forcing all calling systems to switch at once.