Menu Octopus Deploy

z/OS Connect: key features, components, and quick tutorial

What is IBM z/OS Connect?

IBM z/OS Connect is a middleware solution that enables RESTful API access to mainframe applications and data running on IBM z/OS. It acts as a bridge between modern, cloud-native or mobile applications and traditional mainframe services such as CICS, IMS, and Db2.

The tool allows developers to expose existing mainframe programs as REST APIs without modifying the underlying code. This helps organizations modernize legacy systems incrementally, preserving reliability and performance while integrating with contemporary API-driven architectures.

z/OS Connect runs as a server on z/OS and provides a configuration-based approach for defining APIs. It uses descriptors and mappings to transform REST requests into mainframe program calls and to format responses back into JSON. Security is managed through z/OS facilities like RACF, ensuring consistent access control and audit capabilities.

By using z/OS Connect, enterprises can extend mainframe data and logic to cloud platforms, microservices, and web applications, enabling faster development cycles and improved interoperability between legacy and modern environments.

This is part of a series of articles about mainframe modernization.

Key features of z/OS Connect

IBM z/OS Connect includes a range of capabilities designed to simplify API development, enhance security, and support scalable, modern integrations with z/OS systems. Below are the key features:

  • OpenAPI support: Supports both OpenAPI 2 and 3, allowing creation of RESTful APIs that conform to widely adopted API standards.
  • Rapid API creation: Enables quick development of OpenAPI 3-defined APIs using a web-based designer, accelerating integration with mainframe services.
  • Flexible deployment options: Offers native z/OS deployment or containerized deployment using OCI-compliant runtimes, including support for Kubernetes and Red Hat OpenShift.
  • zIIP offloading: Over 99% of the Java-based processing can be offloaded to zIIP processors, helping reduce CPU usage and operational costs.
  • Scalability and performance: APIs can scale dynamically based on demand without reconfiguration, supporting high-volume transactional environments.
  • Security integration: Delivers enterprise-grade security using OpenAPI-based schemes and z/OS security controls, ensuring consistent access management and auditing.
  • Monitoring and auditing: Provides centralized and consistent monitoring for all z/OS APIs, enabling better visibility and control across environments.
  • CI/CD compatibility: Seamlessly integrates with existing CI/CD pipelines to support modern DevOps practices.
  • Decentralized API management: Allows isolated and independently scalable API flows, promoting decentralized ownership and simplified operations.
  • Hybrid cloud enablement: Bridges mainframe applications with modern cloud and distributed environments for hybrid integration.

Components of z/OS Connect

IBM z/OS Connect is structured around several core components that support different stages of the API lifecycle, from development and configuration to deployment, monitoring, and policy management. These components in z/OS Connect 3.0 reflect the evolution toward container-based and modern development environments.

Development tools

z/OS Connect 3.0 introduces a web-based z/OS Connect Designer, available as a container image, that enables rapid API design using OpenAPI 3. It also provides Gradle plug-ins for both API provider and API requester development, supporting automated builds within containerized or started task environments. Additionally, development tools for Visual Studio Code are available with version 3.0, expanding integration with modern IDEs.

Runtime environment

It relies on the z/OS Connect Server, which runs as a started task on z/OS to handle API execution and management. Version 3.0 extends this capability by supporting a server container image, allowing deployment on container platforms such as Kubernetes or IBM z/OS Container Platform. This provides flexibility in how z/OS Connect services are run, either as traditional z/OS started tasks or as containerized services.

Monitoring and observability

For monitoring, z/OS Connect uses SMF (System Management Facility) records to track performance and operational data. Version 3.0 also supports OpenTelemetry for modern, distributed tracing and observability across hybrid environments.

Policy and governance

A built-in Policy component is available in both releases, providing centralized control over API usage, access, and behavior. It ensures consistent enforcement of operational and security policies across all APIs deployed on z/OS Connect.

Tony Kelly Tony Kelly

Tony Kelly is a DevOps marketing leader who drives innovation and awareness of the latest trends in Continuous Delivery.

In my experience, here are tips that can help you better adopt and scale IBM z/OS Connect in modern enterprise architectures:

  1. Use Gradle multi-project builds for API governance:
    As API sprawl grows, split API Provider and Requester projects into modular Gradle subprojects with shared plugins and linting rules. This ensures consistent schema validation, naming conventions, and deployment logic across multiple teams and APIs.
  2. Employ schema-first contracts with OpenAPI linters:
    Enforce schema-first development using OpenAPI linting tools (like Spectral) before z/OS Connect integration. This catches design flaws early (e.g., ambiguous types, missing enums) and prevents mismatches between OpenAPI specs and actual z/OS service behavior.
  3. Integrate with Argo CD for GitOps-style API promotion:
    Store z/OS Connect API artifacts (YAML definitions, WAR files, configuration overrides) in Git and use Argo CD to promote them across dev → QA → prod environments on z/OS Container Platform. This brings auditability, versioning, and safe rollbacks to mainframe APIs.
  4. Use z/OSMF workflows to automate started task deployment:
    Automate the provisioning and configuration of z/OS Connect as a started task using z/OSMF workflows. This codifies the steps to define JCL, assign ports, configure RACF permissions, and set JVM options, eliminating manual errors and onboarding friction.
  5. Enable dynamic OpenTelemetry tracing per API:
    Rather than globally enabling tracing (which can add latency), use policy-driven activation of OpenTelemetry per API or per user context. This allows developers or SREs to dynamically trace issues without affecting global performance.

IBM z/OS Connect system requirements

IBM z/OS Connect can run in both traditional z/OS environments and container-based deployments. Its requirements vary depending on the deployment model (started task or container image). The following summarizes the supported platforms, software prerequisites, and configuration guidelines.

Hardware requirements

The IBM z/OS Connect Server supports two main deployment types: traditional z/OS started tasks and containerized instances.

  • z/OS Connect Server (started task) – Runs on IBM z/OS for version 3.0.
  • z/OS Connect Server (container image) – Runs on container platforms using OCI-compliant runtimes. Supported architectures include zos/s390x, linux/s390x, and linux/amd64.
  • z/OS Connect Designer (container image) – Supported on the same container architectures as the server.
  • Development tools:
    • Visual Studio Code extensions (version 3.0): Windows, macOS, and Linux.
    • API Toolkit and Build Toolkit (version 2.0): Windows, macOS, Linux, and z/OS.

Container support

Both the z/OS Connect Server and Designer container images are supported on OCI-compliant platforms, such as Red Hat OpenShift, IBM z/OS Container Platform, IBM z/OS Container Extensions, Docker Desktop, Rancher, and Podman.

Software requirements

z/OS Connect Server (started task)

  • Requires z/OS V2.5 or later.
  • Minimum release: IBM z/OS Connect 3.0.55 or later.
  • Supported Java runtimes include:
    • IBM Java Technology Edition 8.0.0 or later.
    • IBM Semeru Runtime Certified Edition for z/OS 11.0.21.0 or later (from version 3.0.81).
    • Semeru 17.0.12.0 or later, and Semeru 21.0.0.0 or later (from version 3.0.87).

z/OS Connect Server (container image)

  • Requires an OCI-compliant runtime such as IBM z/OS Container Platform 1.1+ or Red Hat OpenShift 4.9+.

z/OS Connect Designer (container image)

  • Requires an OCI-compliant runtime, e.g., Docker Desktop 19.0.3+.

Development and build tools

  • Visual Studio Code tools (v3.0):
    • Requires Visual Studio Code 1.99 or later.
    • API Provider Gradle plug-in 1.4.11+ and API Requester Gradle plug-in 1.2.6+.
  • Gradle plug-ins compatibility:
    • Provider plug-in 1.0–1.0.2 supports Gradle 6.8.3–8.0.2.
    • Provider 1.1.0–1.4.10 supports Gradle 7.6.1–8.12.1.
    • Provider 1.4.11+ supports Gradle up to 9.0.0.
    • Requester plug-ins follow the same compatibility pattern.

Additional dependencies

  • OpenTelemetry support: Requires IBM CICS Transaction Server 6.3 or later for tracing and observability.
  • Artifact compatibility: WAR files created with z/OS Connect 3.0 must be deployed on servers of the same or newer release. Older servers cannot deploy artifacts built with newer tool versions.
  • Gradle installation: Needed when building or requesting APIs through the z/OS Connect API requester plug-in.

Installation and configuration notes

z/OS Connect installations are performed through SMP/E. After installation, the server must be configured for the desired API mode, either provider or requester. For container deployments, images are pulled and run through supported container orchestration platforms.

Service levels later than those listed are supported if they maintain upward compatibility. Users should verify subsystem (CICS, IMS, Db2) versions in IBM’s product documentation to ensure full integration compatibility.

Tutorial: creating a simple OpenAPI 3.0 document with z/OS Connect

This tutorial walks through creating a basic OpenAPI 3.0 document for integrating a Db2 database using IBM z/OS Connect. The process uses the online Swagger Editor to define a REST API called SalesAPI, which retrieves sales data from Db2. Instructions are adapted from the z/OS Connect documentation.

Step 1: open Swagger Editor

In a web browser, go to https://editor.swagger.io.

The Swagger Editor opens with a sample API called Swagger Petstore. The left pane displays editable OpenAPI source code, and the right pane shows a visual rendering of the API.

Step 2: clear the existing content

Click inside the left-hand editor panel and remove all existing text. This creates a blank workspace for defining a new OpenAPI 3.0 document from scratch. The preview panel will show an empty API definition.

Step 3: start the OpenAPI definition

Enter the following as the first line in the editor:

openapi: 3.0.0

This specifies the OpenAPI version supported by z/OS Connect. Validation errors may appear temporarily until the required sections are added.

Step 4: define basic API information

Add an info object to describe the API:

info:
  title: SalesAPI
  description: SalesManagement API for Db2.
  version: "0.1"

The title and version fields are mandatory. The optional description helps others understand the API’s purpose.

Step 5: specify the server URL

Define the base path for the API using the servers object:

servers:
  - url: /

In z/OS Connect, the contextRoot determines how the API is accessed. Here it is set to the root path (/), but it can be customized as needed.

Step 6: define API paths and operations

Create the main endpoint for retrieving sales data. Start by adding the paths object and define the /sales resource with a GET method:

paths:
  /sales:
    get:
      description: Uses the getSales Db2 z/OS asset.

The description field documents what this operation does.

Step 7: add the response definition

Each operation must include at least one valid HTTP response code. Define a successful "200" response:

      responses:
        "200":
          description: OK

Step 8: define the response content and schema

Specify that the response returns JSON data, and describe the structure of each sales order record using a schema:

          content:
            application/json:
              schema:
                type: array
                items:
                  properties:
                    orderNumber:
                      type: string
                      example: "ON00150"
                    customerFirstName:
                      type: string
                      example: "BRUCE"
                    customerLastName:
                      type: string
                      example: "ADAMSON"
                    orderAmount:
                      type: number
                      example: "2280"

This defines the expected JSON array, where each item represents a sales order with standard fields.

Step 9: save and validate the API definition

Once the YAML is complete, save it locally by selecting File → Save as YAML in the Swagger Editor. The file can then be checked into source control for versioning and collaboration.

Step 10: explore the defined API

If there are no syntax errors, the Swagger Editor displays a preview of the new API. Expand the GET /sales operation to view its description, response type, and example data structure.

This completes the creation of a simple OpenAPI 3.0 document that can be used by z/OS Connect to expose a Db2-based REST API.

Help us continuously improve

Please let us know if you have any feedback about this page.

Send feedback

Tags:

Categories:

Next article
Microservices

More resources