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:
- Clone it to your workstation:
git clone https://github.com/zowe/sample-spring-boot-api-service
- Build & run it:
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:
To deploy this service on z/OS, there are a few steps to complete:
- Create and mount z/OS File System (zFS)
- Deploy artifacts (binaries) to z/OS
- 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.
zfsadm define -aggregate IBMUSER.SAMPLAPI.ZFS -cylinders 100 -volumes WRKD23
IOEZ00248I VSAM linear dataset IBMUSER.SAMPLAPI.ZFS successfully created.
Format the zFS:
zfsadm format -aggregate IBMUSER.SAMPLAPI.ZFS
IOEZ00077I HFS-compatibility aggregate IBMUSER.SAMPLAPI.ZFS has been successfully created
Create a directory to hold the sample API artifacts:
Mount the zFS:
/usr/sbin/mount -v -f IBMUSER.SAMPLAPI.ZFS /u/ibmuser/samplapi
FOMF0502I Mount complete for IBMUSER.SAMPLAPI.ZFS
Next, you’ll need to upload several binary artifacts from your workstation to the newly allocated zFS. You can upload artifacts via
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
In the z/OS Unix Shell, create a directory for 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:
In the z/OS Unix shell, create a config directory:
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
port, and the paths to the
address you can
ping the host name of LPAR from your workstation.
Deploy keystore and
Rather than describe the purposes of
truststore in this article, you can read about them here. For now, we’ll blindly upload the artifacts knowing that they’re needed 😃:
zowe files upload ftu "config/local/keystore.p12" "/u/ibmuser/samplapi/config/keystore.p12" --binary
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:
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:
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
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.
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.