How to Deploy a Zowe Sample API Service to z/OS

First published on May 31, 2019, by Dan Kelosky at

Sample Service Introduction

Externally, regardless of the framework you choose, you use the same pattern to get going. You take a starter project (like the sample), then:

  1. Clone it to your workstation: git clone
  2. Build & run it: gradlew bootRun

Once the build completes, the service starts:

Console messages from build and run gradle task

Once started, you can try the api/v1/greeting API from your browser to get some “Hello, world!” JSON:

After bypassing security errors and signing in with user and password “zowe” you can see the greeting API response

Deployment Overview

  1. Create and mount z/OS File System (zFS)
  2. Deploy artifacts (binaries) to z/OS
  3. Construct JCL and run the service as a batch job

Create and Mount a zFS

Allocate a z/OS File System (zFS) using zfsadm:

zfsadm define -aggregate IBMUSER.SAMPLAPI.ZFS -cylinders 100 -volumes WRKD23

Example response:

IOEZ00248I VSAM linear dataset IBMUSER.SAMPLAPI.ZFS successfully created.

Format the zFS:

zfsadm format -aggregate IBMUSER.SAMPLAPI.ZFS

Example response:

IOEZ00077I HFS-compatibility aggregate IBMUSER.SAMPLAPI.ZFS has been successfully created

Create a directory to hold the sample API artifacts:

mkdir /u/ibmuser/samplapi

Mount the zFS:

/usr/sbin/mount -v -f IBMUSER.SAMPLAPI.ZFS /u/ibmuser/samplapi

Example response:

FOMF0502I Mount complete for IBMUSER.SAMPLAPI.ZFS

Deploy Artifacts

Deploy the Sample Service API JAR

The default artifact will be placed in build/libs/zowe-apiservice-0.0.1-SNAPSHOT.jar.

In the z/OS Unix Shell, create a directory for the zowe-apiservice-0.0.1-SNAPSHOT.jarmkdir /u/ibmuser/samplapi/jars

Upload the zowe-apiservice-0.0.1-SNAPSHOT.jar as a binary artifact:

zowe files upload ftu build/libs/zowe-apiservice-0.0.1-SNAPSHOT.jar "/u/ibmuser/samplapi/jars/zowe-apiservice-0.0.1-SNAPSHOT.jar" --binary

Deploy the Sample Service Configuration YAML

In the z/OS Unix shell, create a config directory: mkdir /u/ibmuser/samplapi/config

Then, upload the config/local/application.yml as a binary artifact:

zowe files upload ftu "config/local/application.yml" "/u/ibmuser/samplapi/config/application.yml" --binary

If this file YAML is edited on z/OS, it must remain in ASCII format (not EBCDIC).

Lastly, add the “zos” profile to the first line, change the addressport, and the paths to the keystore and truststore locations:

Change the address and port for access from off-platform

For the address you can ping the host name of LPAR from your workstation.

Deploy keystore and truststore

Upload keystore:

zowe files upload ftu "config/local/keystore.p12" "/u/ibmuser/samplapi/config/keystore.p12" --binary

Upload truststore:

zowe files upload ftu "config/local/truststore.p12" "/u/ibmuser/samplapi/config/truststore.p12" --binary

Construct JCL & Run

Start via Java Commands

java -Xquickstart -jar /u/ibmuser/samplapi/jars/zowe-apiservice-0.0.1-SNAPSHOT.jar --spring.config.additional-location=file:/u/ibmuser/samplapi/config/application.yml

Here is a snippet of the messages seen after startup on z/OS:

java command using git bash terminal and ssh to z/OS Unix

From here, you can stop the server via: Ctrl+C

Start via z/OS Batch Job

This will need customized for your installations location of java and where you put the sample API service

Submit the JCL and view output in the SYSPRINT DD:

You can stop the server via: STOP SAMPLAPI.

Running Example

You need to use your real mainframe credentials here instead of “zowe” because the zos profile activates SAF-backed security. That is, SAF is used to authenticate to the API with basic authentication.