Legacy Mainframe Modernization with API Layer

Wrapped 40-year-old mainframe with modern API layer, enabling mobile app integration and third-party connections without mainframe code changes.

[Overview] System Overview

A government agency operated critical citizen services on a 40-year-old mainframe. The system processed 1.2 million daily transactions with exceptional reliability. However, there was no programmatic access-all interaction was through 2000+ terminal screens. Mobile app development was impossible.

We created an API layer that wrapped mainframe functionality, exposing RESTful APIs that enabled mobile app development, third-party integration, and modern web interfaces-all without modifying mainframe code.

The approach preserved the mainframe investment while enabling modern capabilities. This was pragmatic modernization-improving what needed improvement without risking what worked.

[Context] Situation before

Citizen interaction required visiting offices or calling phone support. Wait times exceeded 2 hours. Staff shortages made hiring insufficient. Public satisfaction was critically low.

##### Integration Failure

Third-party systems that needed mainframe data used screen scraping-fragile and slow. Any mainframe screen change broke integrations.

##### Mobile Imperative

Citizens expected mobile access. Competing services offered apps. The agency was seen as outdated and unresponsive.

[Diagnosis] The real problem

The mainframe was not the problem-it was reliable. The problem was the interface. Screen-based interaction was incompatible with modern integration patterns.

Replacing the mainframe was high-risk and would take years. The agency needed mobile capabilities within 12 months. A wrapper approach could deliver quickly.

Understanding the root cause changed everything.

[Boundaries] Working constraints

Government system modernization has unique constraints.

Constraints are features, not obstacles. They guide design decisions.

[Decisions] Key tradeoffs

Modernization approach balanced risk against speed.

status="rejected" title="Full Replacement" description="Replace mainframe with modern system" reasoning="Too risky, too expensive, too slow. Years of development before any benefit." /> status="rejected" title="Screen Scraping APIs" description="Wrap existing screens with APIs" reasoning="Fragile and slow. Any screen change breaks APIs. Performance limited by screen rendering." /> status="chosen" title="Transaction API Layer" description="Direct transaction access with API wrapper" reasoning="Interacts at transaction level, not screen level. More stable and performant. Mainframe provides batch transaction interfaces." />

[Design] Architecture design

The API layer interacts with mainframe via transaction protocols (CICS), not screen scraping. Modern API gateway exposes RESTful endpoints. Request mapping translates REST to mainframe transaction format.

Response mapping transforms mainframe data to JSON. Caching reduces mainframe load for read-heavy endpoints.

"type": "architecture", "title": "Mainframe API Wrapper Architecture", "description": "API layer exposing mainframe transactions", "components": [ "name": "Mobile App", "type": "user" }, "name": "Web Portal", "type": "user" }, "name": "API Gateway", "type": "service", "description": "Kong" }, "name": "Transaction Mapper", "type": "service", "description": "REST to CICS" }, "name": "Cache", "type": "database", "description": "Redis" }, "name": "Mainframe", "type": "external", "description": "CICS transactions" } ], "connections": [ "from": "Mobile App", "to": "API Gateway", "label": "REST API" }, "from": "Web Portal", "to": "API Gateway", "label": "REST API" }, "from": "API Gateway", "to": "Transaction Mapper", "label": "Validated request" }, "from": "Transaction Mapper", "to": "Cache", "label": "Check cache" }, "from": "Transaction Mapper", "to": "Mainframe", "label": "CICS call" } ], "boundaries": [ "name": "API Platform", "contains": [ "API Gateway", "Transaction Mapper", "Cache" ] } ] }

{/* Diagram: sequence - API Request Flow */}
{/* ```json
{
  "type": "sequence",
  "title": "API Request Flow",
  "description": "REST request translated to mainframe transaction",
  "components": [
    {
      "name": "Client",
      "type": "user"
    },
    {
      "name": "Gateway",
      "type": "service"
    },
    {
      "name": "Mapper",
      "type": "service"
    },
    {
      "name": "Mainframe",
      "type": "external"
    }
  ],
  "connections": [
    {
      "from": "Client",
      "to": "Gateway",
      "label": "GET /citizens/123"
    },
    {
      "from": "Gateway",
      "to": "Mapper",
      "label": "Validated"
    },
    {
      "from": "Mapper",
      "to": "Mainframe",
      "label": "CICS CITINQ(123)"
    },
    {
      "from": "Mainframe",
      "to": "Mapper",
      "label": "COBOL copybook"
    },
    {
      "from": "Mapper",
      "to": "Client",
      "label": "JSON response"
    }
  ]
}

[Approach] Execution model

APIs were developed incrementally-high-volume transactions first. Each API was validated against mainframe behavior before release.

Mobile app development started in parallel. APIs and app launched together after 10 months of development.

[Results] Measurable outcomes

Mobile app launched within 12 months. 500,000 citizens used the app in the first year. Office visits declined 30% as self-service increased.

Third-party integrations became possible. Partner organizations integrated via API instead of manual processes.

Mainframe remained stable throughout. Zero changes to mainframe code were required. The reliable core continued operating.

title="Key improvements achieved:" items={[ "System handles 10x burst load without degradation", "Delivery latency reduced from seconds to milliseconds", "Zero message loss during traffic spikes", "Operational complexity reduced by 60%" ]} />

[Anti-patterns] What could have gone wrong

Without modernization, citizen frustration would have continued growing. Political pressure was mounting. Eventually, a risky replacement project would have been forced.

Third-party integration would have remained manual. Partner organizations were threatening to stop cooperation due to process friction.

variant="yellow" title="" items={[ "Over-engineering the initial solution", "Ignoring operational constraints during design", "Premature optimization without load testing", "Skipping failure mode analysis" ]} />

[Applicability] Where this pattern applies

API wrapping applies wherever legacy systems are too reliable or risky to replace. Banking, insurance, government, and utilities all have similar mainframe situations.

The pattern works when the legacy system has stable transaction interfaces. Pure screen-based systems require more complex approaches.

Every system is different. Context always matters.