Sample Service Introduction

You can learn what a RESTful web service is and how to build one with Spring alone, and Spring (which Java-based) isn’t the only choice when building web services. For example, Node.js runs on z/OS which allows JavaScript / TypeScript frameworks to used to build your APIs if you prefer those technologies.

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 https://github.com/zowe/sample-spring-boot-api-service
2. Build & run it: gradlew bootRun

Once the build completes, the service starts:

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

Deployment Overview

To deploy this service on z/OS, there are a few steps to complete:

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

First, you need a space (a zFS) to deploy the API artifacts. Login to z/OS Unix Shell (you may need privileged authority to issue the command examples below, e.g. superuser).

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

Next, you’ll need to upload several binary artifacts from your workstation to the newly allocated zFS. You can upload artifacts via ftp, sftp, scp or Zowe CLI. zowe commands will be used in the remaining examples.

Deploy the Sample Service API JAR

To obtain the sample service JAR (which contains the runnable API service code), run gradlew build from your workstation sample service project.

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.jar: mkdir /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

Next, create a directory for the application.yml. This will contain configuration overrides for when the service is started on z/OS using a Spring run-time parameter: --spring.config.additional-location.

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 address, port, and the paths to the keystore and truststore locations:

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

Deploy keystore and truststore

Rather than describe the purposes of keystore and truststore in this article, you can read about them here. For now, we’ll blindly upload the artifacts knowing that they’re needed 😃:

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

With all artifacts uploaded, you can run the sample server from the z/OS Unix Shell using java commands or via a started task / batch job with JCL.

Start via Java Commands

To start the server using a java command, you can issue:

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:

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

Start via z/OS Batch Job

Customize the JCL below to run the server as a batch job:

Submit the JCL and view output in the SYSPRINT DD:

You can stop the server via: STOP SAMPLAPI.

Running Example

When the server is started (either through a java command or JCL), you can test the sample api/v1/greeting API through your web browser (as described above) — you only need to substitute the proper hostname / IP in place of localhost.

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.

Summary

This covered the steps of cloning a sample API service and deploying the service to z/OS. A terse description of the steps can also be found here. In the future, I hope to describe how to make this service discoverable in the Zowe API ML, some aspects of security, and how to invoke native (z/OS linkage) services in an API request.