README.md

Zowe Sample API Service

Use this sample Spring Boot REST API as a starting point to create a new z/OS-based service that:

• Supports basic auth via SAF validation (when running on z/OS)
• Can invoke traditional z/OS services via assembler or metal C interface through JNI
• Is automatically discoverable via the Zowe API Mediation Layer

Prerequisites

Following platform is required to run the application:

• Java JDK 8

  • For example: https://adoptopenjdk.net/releases.html?variant=openjdk8&jvmVariant=openj9
  • Set JAVA_HOME system variable with a valid JDK path and add ${JAVA_HOME}/bin to the PATH variable

• Zowe CLI (optional)

  • For example: https://www.npmjs.com/package/@zowe/cli

Quick Start

Download the source code of the sample from https://github.com/zowe/sample-spring-boot-api-service/releases/latest/download/zowe-rest-api-sample-spring.zip and unzip it:

curl -OL https://github.com/zowe/sample-spring-boot-api-service/releases/latest/download/zowe-rest-api-sample-spring.zip
unzip zowe-rest-api-sample-spring.zip
cd zowe-rest-api-sample-spring

Build you application:

./gradlew build

Note: On Windows use gradlew instead of ./gradlew

Start your application:

./gradlew bootRun

Use the Application

Open https://localhost:10080/api/v1/greeting in your browser or favorite REST API client (for example HTTPie, REST Client for VSCode, or Insomnia.

Use zowe as the username and zowe as the password.

The default page https://localhost:10080/ opens Swagger UI with the API Documentation.

Customize and Extend Your Application

For further reference, please consider the following sections:

• Building New APIs
• Changing the Service Configuration
• Adding New REST Controller
• Testing REST APIs
• External Configuration
• Logging
• Setup HTTPS and Create TLS/SSL Certificates
• Integrate with Zowe API Mediation Layer
• Web Security
• API Client Authentication
• Deployment to z/OS
• z/OS Security
• z/OS Native OS Linkage
• Error Handling
• Java Debugging

Learn More about Gradle and Spring Boot

Reference Documentation

For further reference, please consider the following sections:

• Official Gradle documentation

Guides

The following guides illustrate how to use some features concretely:

• Building a RESTful Web Service
• Serving Web Content with Spring MVC
• Building REST services with Spring
• Building a RESTful Web Service with Spring Boot Actuator
• Setting Up Swagger 2 with a Spring REST API
• Spring Security Basic Authentication
• Spring Security Authentication Provider

Additional Links

These additional references should also help you:

• Gradle Build Scans – insights for your project's build