Modern applications require REST/JSON interfaces, but legacy CICS systems use proprietary protocols. This white paper describes a FastAPI-based service that bridges this gap, transforming CICS transactions into standardized endpoints while preserving mainframe fidelity.

Executive Summary

Financial institutions face a critical dilemma: modern digital channels demand agile, stateless REST APIs, yet core banking logic resides in stateful, proprietary CICS/IMS mainframe environments. "Rip and replace" strategies often fail due to the immense risk of rewriting decades of business logic.

This paper presents a "Lift and Refactor" approach: a FastAPI-based middleware that exposes COBOL transactions as microservices. It integrates with CICS emulators, maps legacy return codes to HTTP status, ensures transactional integrity, and provides audit logging for enterprise banking operations.

Architecture

Core Components

FastAPI App (main.py): Serves as the modern entry point, providing endpoints for inquiry, transfer, and logging with auto-generated Swagger documentation.
CICS Client Integration: Leverages a MockCICSClient to simulate backend calls, ensuring the API layer remains decoupled from the mainframe transport.
Data Models: Uses Pydantic for strict request/response validation, ensuring fields like account_id and amount (Decimal) meet banking precision standards.
Error Mapping: Translates CICS return codes (e.g., 00=Normal) to appropriate HTTP status codes (200 OK, 400 Bad Request), bridging the semantic gap between legacy and modern systems.

Data Flow

The transaction lifecycle ensures end-to-end fidelity:

Client Request: Mobile/Web app sends JSON payload.
Transformation: Middleware converts JSON to CICS Channel/Container format.
Execution: Mock Program (BANKINQ/BANKTFR) executes business logic.
Response: CICS output is mapped back to JSON for the client.

Key Features

Standardized Endpoints:
- POST /v1/account/inquiry: Retrieves balance using WK-INQ fields.
- POST /v1/account/transfer: Executes funds transfer with full syncpoint control.
- GET /v1/transactions/log: Provides a transparent audit trail.
Security: Implements X-API-KEY authentication to secure access to sensitive legacy functions.
Observability: Structured logging and status mapping provide visibility into mainframe "black box" operations.

COBOL Emulation Details

To ensure the Python layer behaves exactly like the mainframe, specific emulation techniques are employed:

Data Translation: A dedicated COBOLDataMapper handles the conversion between Python types and COBOL formats (e.g., COMP-3 packed decimals to Python Decimals).
Transaction Management: Full emulation of EXEC CICS LINK and syncpoints ensures that writes are atomic and consistent.
Fidelity: Responses include CICS Transaction IDs (TS-ID) and original return codes for complete traceability.

Conclusion

This architecture provides a low-risk, high-value path to modernization. By wrapping legacy logic in a robust API layer, institutions can enable cloud-native applications to leverage proven mainframe banking logic without the risks associated with protocol changes or full rewrites.