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

By January 15, 2020January 23rd, 2020Blog, Zowe, Zowe Development Updates

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.