Onboarding Custom Mainframe REST Services to Zowe API Mediation Layer (APIML) with Eureka Discovery
Executive Summary: Onboarding Custom Mainframe REST Services to Zowe API Mediation Layer (APIML) with Eureka Discovery
The Zowe API Mediation Layer (APIML) provides a central enterprise gateway, SSO, and service discovery for all mainframe REST APIs. Learn how to onboard custom z/OS Connect or Java Spring Boot services using Netflix Eureka registration and Swagger/OpenAPI schemas.
1 Problem Statement & Architecture Context: Onboarding Custom Mainframe REST Services to Zowe API Mediation Layer (APIML) with Eureka Discovery
Enterprises building dozens of microservices on z/OS find their cloud developers overwhelmed by fragmented mainframe endpoints, multiple port numbers, varying authentication methods, and lack of dynamic failover.
2 Technical Root Cause & Architecture Mechanics
Individual mainframe subsystems (z/OSMF, z/OS Connect, CICS, IMS Mobile) run on disparate TCP ports with differing security schemes.
The Zowe API Mediation Layer (APIML) implements an enterprise API Gateway based on Spring Cloud Gateway and Netflix Eureka:
- Provides a single secure entry point (
https://mainframe-gateway:7554/api/v1/...). - Validates enterprise tokens (JWT / RACF passTickets) once at the perimeter.
- Auto-discovers active backend service instances dynamically.
3 Implementation Guide & Modernization Strategy
# 1. Create the Service Onboarding Configuration (api-defs.yml)
Define your service metadata:
serviceId: banking-core-service
title: Enterprise Core Banking REST API
description: Real-time accounts, ledger posting, and card transactions via CICS & DB2
instance:
homePageUrl: https://zsys1.stackmf.internal:10443/
statusPageUrl: https://zsys1.stackmf.internal:10443/status
healthCheckUrl: https://zsys1.stackmf.internal:10443/healthz
routedServices:
- gatewayUrl: api/v1/banking
serviceUrl: /api/v1
routes:
- gatewayUrl: api/v1/banking
serviceUrl: /api/v1
apiInfo:
- version: 1.0.0
swaggerUrl: https://zsys1.stackmf.internal:10443/swagger/v3/api-docs
authentication:
scheme: httpBasicPassTicket
applid: CICSPROD
# 2. Register Service with the Zowe Discovery Service
Post the registration payload to APIML Discovery Service:
curl -X POST https://apiml.stackmf.internal:7553/eureka/apps/BANKING-CORE-SERVICE -H "Content-Type: application/json" -d @api-defs.json
# 3. Invoke Service via Unified APIML Gateway
Cloud clients now invoke the API via standard HTTPS:
curl -X GET https://apiml.stackmf.internal:7554/banking-core-service/api/v1/accounts/49201 -H "Authorization: Bearer <ZOWE_JWT_TOKEN>"
Technical Specifications Matrix
| Attribute | Specification |
|---|---|
| Target Environment | IBM z/OS • Modernisation & Cloud |
| Key Technologies | Zowe, APIML, REST API |
| Delivery SLA | Accelerated Sprint Delivery via StackMF Pods |
| Technical Reviewer | Anshu, Chief Technology Architect • StackMF Architecture Pod |
Production Readiness & Verification Checklist
- Always register health check endpoints (`/healthz`) so APIML routes around degraded LPARs automatically.
- Use PassTickets to authenticate seamlessly to backend CICS/IMS regions without exposing user passwords.
- Publish OpenAPI 3.0 specifications to the Zowe API Catalog for developer self-service documentation.
? Frequently Asked Questions
What is the root cause of Onboarding Custom Mainframe REST Services to Zowe API Mediation Layer (APIML) with Eureka Discovery? ↓
How do you resolve Onboarding Custom Mainframe REST Services to Zowe API Mediation Layer (APIML) with Eureka Discovery in production? ↓
How can teams prevent Onboarding Custom Mainframe REST Services to Zowe API Mediation Layer (APIML) with Eureka Discovery in enterprise pipelines? ↓
Recommended Technical Runbooks
Modernizing COBOL Copybooks to OpenAPI 3.0 REST APIs using IBM z/OS Connect
Real-Time Mainframe Change Data Capture (CDC) to Apache Kafka: Streaming DB2 & VSAM to Cloud
Dual-Stack COBOL and Java Interoperability on z/OS using 64-bit IBM Semeru Runtime
Authoritative Reference Documentation
Official IBM manuals, Redbooks, and vendor technical advisories:
This diagnostic runbook is published by StackMF Technologies LLP for educational and architectural reference only. All code snippets, JCL, and procedures are provided "AS IS" without warranty of any kind. Always test changes thoroughly in non-production sysplex environments prior to production rollout.
IBM, z/OS, CICS, Db2, IMS, RACF, and IDz are registered trademarks of International Business Machines Corporation. Broadcom, CA-7, and Endevor are trademarks of Broadcom Inc. All other trademarks belong to their respective owners and are referenced under the Nominative Fair Use Doctrine (US Lanham Act 15 U.S.C. ยง 1125 / Section 30 of the Indian Trade Marks Act, 1999) solely for technology compatibility and diagnostic identification. StackMF Technologies LLP is an independent consulting entity not affiliated with or endorsed by these vendors. View Full Legal & IP Policy →
Struggling with Critical Mainframe Incidents or Vendor Renewal Pressure?
StackMF deploys certified Senior Mainframe Engineers fluent in both z/OS legacy internals (COBOL, DB2, CICS, VSAM, CA-7, Endevor) and modern cloud stacks (React, Kafka, AWS, Git). Onboard dedicated pods in 48 hours or cut Broadcom licensing by 60%.