A mobile banking app developer needs to display a customer's account summary. The data lives in a CICS COBOL program that has run the bank's core logic for thirty years. The developer knows REST and JSON. She has never heard of CICS, has no idea what a commarea is, and has no intention of learning. She needs an endpoint she can call with a standard HTTP GET request and get back JSON.
The CICS web services approach covered in the previous post would require generating WSDL, configuring SOAP pipelines, and working with XML. That is a reasonable integration for system-to-system SOAP consumers, but it is the wrong tool for a mobile developer who expects a REST API with an OpenAPI document she can browse in Swagger.
z/OS Connect is the answer to that problem. It sits between the modern world of REST and JSON and the mainframe world of CICS, MQ, IMS, and DB2. A developer describes the API she wants. A z/OS administrator maps it to the underlying mainframe program. The mobile developer calls a REST endpoint, gets JSON back, and never needs to know what is running underneath. This post covers what z/OS Connect is, how it is structured, and how both sides of that boundary work.
What z/OS Connect Is
z/OS Connect (formally IBM z/OS Connect, previously z/OS Connect Enterprise Edition) is an API gateway that runs on z/OS and provides REST/JSON access to mainframe subsystems. It runs on WebSphere Liberty: a lightweight Java EE application server that IBM ships as part of z/OS. From the network's perspective, z/OS Connect is an HTTP server that accepts REST requests and returns JSON responses. From the mainframe's perspective, it is a Java application running in a Liberty JVM server that translates those requests into calls to CICS programs, MQ queues, IMS transactions, or DB2 stored procedures.
The current generation is z/OS Connect 3.0, which supports the OpenAPI 3.0 specification. The previous generation (z/OS Connect EE) used OpenAPI 2.0 (Swagger). Both generations are in production at many sites. The 3.0 architecture uses WAR files for API deployment; the EE architecture used SAR and AAR files. This post covers the 3.0 model, noting where the EE model differs.
z/OS Connect connects to CICS via IPIC (IP InterConnectivity), a TCP/IP-based connection between Liberty and a CICS region. As of version 3.0.88, it can also run inside a CICS Liberty JVM server and use a direct JCICS connection for lower latency when calling programs in the same CICS region.
How an API is Built: The 3.0 Model
Building a z/OS Connect 3.0 API involves three things: an OpenAPI 3.0 document describing the REST interface, a mapping that connects each API operation to a backend mainframe service, and a WAR file that packages everything for deployment into Liberty.
The OpenAPI Document
The starting point is an OpenAPI 3.0 document: a YAML or JSON file that describes the REST API in standard terms. It lists the endpoints, HTTP methods, request parameters, request body schemas, and response schemas. This document is the contract between the API and its consumers. It can be written by the API developer from scratch (API-first design) or generated from an existing z/OS asset description.
Once the OpenAPI document is ready, it is imported into the z/OS Connect Designer: a browser-based tool (distributed as a container image) that provides a visual interface for mapping API operations to backend services. The Designer connects to the live CICS region via IPIC to discover available programs and their data structures, allowing the developer to drag-and-drop field mappings between the JSON schema and the COBOL commarea layout.
The Service Archive (SAR) and Mapping
For each backend mainframe asset, z/OS Connect needs a service description: a file that captures the data structure of the COBOL program's commarea or the MQ message format. In the 3.0 model, this is expressed as a JSON schema derived from the COBOL copybook, generated by tooling that reads the copybook and produces the equivalent JSON type definitions.
The mapping layer, configured in the Designer, specifies how each field in the incoming JSON request maps to a field in the COBOL commarea, and how each field in the commarea response maps to a field in the JSON response. COBOL uses packed decimal (`COMP-3`) and binary integers (`COMP`) that have no direct JSON equivalent. z/OS Connect handles these type conversions at runtime: a `PIC S9(8)V99 COMP-3` balance field becomes a JSON number with two decimal places. The mapping rules describe exactly how this conversion happens for every field.
The WAR File and Deployment
Once the mapping is defined, a Gradle build compiles the OpenAPI document and mapping into a standard Java WAR file. The WAR file is deployed to the Liberty server running z/OS Connect, exactly as any Java web application is deployed to Liberty. Liberty hot-deploys the WAR without restarting the server: the new API is available within seconds of the file being placed in the dropins directory.
The deployed API is immediately discoverable via Swagger UI, served directly from the z/OS Connect server. A developer can browse to the server's URL, see the API documentation, and test requests interactively without any additional tooling.
How a Request Flows
A mobile app sends an HTTP GET request to `https://mainframe.bank.com:9443/accounts/12345678`. z/OS Connect receives the request, authenticates it using SAF/RACF (the user identity in the request's OAuth token or HTTP Basic credentials is checked against RACF), and routes it to the API provider WAR that owns the `/accounts/{accountId}` path.
The API provider reads the `accountId` path parameter from the URL and places it into the COBOL commarea field mapped to it: `CA-ACCOUNT-NUMBER PIC 9(10)`. With the commarea populated, z/OS Connect issues a call to the CICS program via IPIC. CICS receives it as a standard program link, runs the COBOL program, and returns the commarea with the account data populated.
z/OS Connect reads the commarea and applies the mapping in reverse. Each commarea field is converted to its JSON equivalent and assembled into a JSON response object. The HTTP response is returned to the mobile app with status 200 and a Content-Type of `application/json`.
The entire round trip, from HTTP request to JSON response, typically takes the time the CICS program takes to execute plus a few milliseconds of z/OS Connect overhead. For a buffered CICS transaction reading from a VSAM file, this is 10 to 30 milliseconds end to end.
Security Integration
z/OS Connect integrates directly with z/OS security through SAF (System Authorization Facility) and RACF. Every inbound API request is authenticated and authorized before it reaches the backend program. This integration is one of z/OS Connect's most operationally significant features: it means API security is enforced using the same RACF profiles and rules that protect every other mainframe resource, rather than a separate API gateway security model.
Authentication supports several mechanisms: HTTP Basic authentication (user ID and password validated against RACF), OAuth 2.0 bearer tokens, client certificates (mutual TLS), and JWT tokens. All of these ultimately resolve to a z/OS user identity that RACF then checks against resource profiles.
Authorization uses the RACF `EJBROLE` class or custom resource classes to control which users can invoke which APIs. A RACF profile can restrict the `/payments` API to members of a specific group, while allowing the `/accounts` API to a broader set of users. These are standard RACF PERMIT commands, managed by the mainframe security team using the same tools they use for every other RACF administration task.
Every API invocation generates an SMF 123 record. This record captures the user identity, the API name, the HTTP method, the response code, and the elapsed time. SMF 123 records feed into SIEM systems, compliance reporting, and capacity planning. The same SMF infrastructure used for CICS and DB2 monitoring captures z/OS Connect API traffic, giving operations teams a single telemetry stream for the entire mainframe workload.
The API Requester: Outbound REST from COBOL
z/OS Connect also works in the opposite direction. A CICS COBOL program can call an external REST API without any Java code, HTTP libraries, or XML. The API requester feature handles the outbound call, JSON construction, and response parsing on the COBOL program's behalf.
The API requester is defined as an ARA (API Requester Archive) file that describes the external REST API and how the COBOL data structures map to its JSON schema. The COBOL program places its request data into a commarea or container, issues a CICS LINK to the API requester stub, and gets the response back in the same commarea. The JSON construction, HTTP transmission, and JSON parsing all happen inside z/OS Connect, invisibly to the COBOL program.
*> COBOL program calling an external fraud scoring REST API via z/OS Connect
*> The ARA handles all JSON and HTTP work
WORKING-STORAGE SECTION.
01 WS-FRAUD-REQUEST.
05 WS-ACCOUNT-NUMBER PIC 9(10).
05 WS-TRANSACTION-AMT PIC S9(8)V99 COMP-3.
05 WS-MERCHANT-CODE PIC X(6).
01 WS-FRAUD-RESPONSE.
05 WS-FRAUD-SCORE PIC S9(4) COMP.
05 WS-RISK-LEVEL PIC X(6).
PROCEDURE DIVISION.
CHECK-FRAUD.
MOVE ACCT-NUMBER TO WS-ACCOUNT-NUMBER
MOVE TRANS-AMOUNT TO WS-TRANSACTION-AMT
MOVE MERCH-CODE TO WS-MERCHANT-CODE
*> Link to the z/OS Connect API requester stub
EXEC CICS LINK
PROGRAM('FRAUDARA')
COMMAREA(WS-FRAUD-REQUEST)
LENGTH(LENGTH OF WS-FRAUD-REQUEST)
RESP(WS-RESP)
END-EXEC
IF WS-RESP = DFHRESP(NORMAL)
EVALUATE WS-RISK-LEVEL
WHEN 'HIGH '
PERFORM DECLINE-TRANSACTION
WHEN 'MEDIUM'
PERFORM FLAG-FOR-REVIEW
WHEN OTHER
PERFORM APPROVE-TRANSACTION
END-EVALUATE
ELSE
PERFORM HANDLE-FRAUD-SERVICE-ERROR
END-IF.The COBOL program never constructs JSON, never opens a TCP socket, and never parses an HTTP response. It calls a CICS program (`FRAUDARA`) that z/OS Connect installed into the CICS region as the API requester stub. That stub forwards the commarea data to z/OS Connect over IPIC, which makes the outbound REST call, receives the response, maps the JSON back to binary fields, and returns the populated commarea to the COBOL program.
This pattern is particularly valuable for modernization programs: existing CICS applications can consume cloud-based services (fraud detection, address validation, credit scoring) without any modification to the COBOL programs themselves beyond adding the CICS LINK call.
MQ Integration
z/OS Connect can also map REST API calls to MQ queues rather than CICS programs. An inbound REST POST request becomes a message put onto an MQ queue. The response, when required, is read from a reply queue. This pattern is appropriate for asynchronous processing: the caller submits a request and either polls for a result or is notified when it is ready.
For one-way operations (fire and forget), z/OS Connect puts the message onto the queue and returns HTTP 202 (Accepted) immediately. The downstream consumer processes the message in its own time. This is the REST equivalent of the MQ triggering pattern covered in the previous post, with z/OS Connect providing the REST-to-MQ translation layer.
Failure Modes
The most common operational failure is a backend timeout. z/OS Connect waits for a response from CICS or MQ for a configured period. If the backend does not respond in time, z/OS Connect returns HTTP 504 (Gateway Timeout) to the caller. The cause is almost always a CICS transaction running longer than expected, a DSA storage wait (covered in the storage management post), or a CICS region that is SOS or unavailable.
An authentication failure produces HTTP 401 (Unauthorized). The RACF check for the provided credential failed. Common causes: expired password, revoked user ID, or a JWT token whose signing key is not trusted by the z/OS Connect SAF configuration.
An authorization failure produces HTTP 403 (Forbidden). The user authenticated successfully but RACF denied access to the specific API resource. The fix is a RACF PERMIT command for the relevant profile, followed by a SETROPTS RACLIST refresh if the class is RACLISTed.
A mapping error produces HTTP 500. This typically means the commarea returned by the CICS program has a field in a state the mapping did not anticipate: a numeric field containing non-numeric data (which would be `ASRA` in pure CICS, but z/OS Connect catches it at the mapping stage), or a field length mismatch between the deployed WAR's mapping and the actual COBOL program's commarea. The z/OS Connect messages log and Liberty trace provide the detailed diagnostics.
z/OS Connect vs CICS Web Services
Both CICS web services (covered in the previous post) and z/OS Connect expose CICS programs to external callers. The key differences are worth stating clearly:
- Protocol: CICS web services use SOAP over HTTP. z/OS Connect uses REST over HTTP with JSON. The right choice depends on what the consumer expects.
- Tooling: CICS web services use WSDL, the CICS pipeline model, and the `wsbind` generator. z/OS Connect uses OpenAPI 3.0, the z/OS Connect Designer, and Gradle builds. The z/OS Connect tooling is more familiar to cloud-native developers.
- Scope: CICS web services are CICS-specific. z/OS Connect integrates CICS, MQ, IMS, DB2, and batch from a single gateway with a unified OpenAPI model.
- Security: Both use SAF/RACF. z/OS Connect's security model is more comprehensive, with native OAuth 2.0 and JWT support designed for API-scale authentication.
- Deployment: CICS web services are deployed by installing `wsbind` files into CICS and scanning the pipeline. z/OS Connect APIs are deployed as WAR files into Liberty using standard Java application server tooling.
In practice, most modern mainframe integration programs use z/OS Connect for new REST APIs and retain existing CICS SOAP web services for established system-to-system integrations. The two coexist comfortably on the same z/OS system.
Summary
z/OS Connect is the bridge between the REST/JSON world and the mainframe. It runs on WebSphere Liberty on z/OS, accepts inbound REST requests described by OpenAPI 3.0 documents, maps JSON to COBOL binary data structures, calls CICS programs via IPIC, and returns JSON responses. The mobile developer who calls it sees a standard REST API. The COBOL program that services it sees a standard CICS LINK call. Neither side needs to understand the other's world.
In the outbound direction, the API requester gives COBOL programs access to external REST services through the same CICS LINK mechanism. A thirty-year-old COBOL program can call a cloud-based fraud scoring API without a single line of Java or a single HTTP library, because z/OS Connect handles the translation.
Security is enforced at every layer: SAF/RACF authenticates and authorizes every request, and SMF 123 records provide the audit trail that compliance and operations teams require. The result is an API gateway that combines the openness of the REST ecosystem with the security, reliability, and operational discipline of the mainframe platform.
Part of the Mainframe Decoded series — IBM Z and z/OS, clearly explained for engineers.