OpenAPI 3 API requester Sample

A sample z/OS Connect API requester project showing how to call an OAS3 defined API from a CICS, IMS or standalone COBOL application. Equivalent PL/I applications are also provided.

Introduction

This Redbook API requester sample implements a very simple IBM Redbook information application written in Java and hosted in Liberty. This application implements an OpenApi 3.0 described API. See the Sub Gradle project RedbookApi redbookapi.yaml file for a full description of the operations. For a PL/I usage please use RedbookApiPLI.

This project's gradle build will build the remote endpoint RedbookAPI application war file and also generate the z/OS Connect API requester war files for COBOL and PLI.

Instructions

Follow the instructions in the IBM Documentation for details on how to build, deploy and run this tutorial sample.

Structure

• The COBOL directory contains the CICS COBOL program BAQHRBKC.cbl, IMS COBOL programs BAQHRBKB.cbl and BAQHRBKT.cbl and the standalone COBOL application BAQHRBKZ.cbl.
• The COPY directory contains example COBOL copybooks generated by building the RedbookApi requester project. Also includes BAQHCIMS.cpy for IMS related constants, functions and data structures.
• The CSD directory contains the CICS CSD file BAQHRBKD.csd necessary for configuring the CICS COBOL program to CICS.
• The deploy/api directory contains the sample server.xml for a Liberty server installed with z/OS Connect. This runs the z/OS Connect API requester WAR and the Redbook endpoint application WAR.
• The INCLUDE directory contains example PL/I copybooks generated by building the RedbookApiPLI requester project. Also includes BAQHCIMS.pli for IMS related constants, functions and data structures.
• The PLI directory contains the CICS PL/I program BAQHRBKC.pli, IMS PL/I programs BAQHRBKB.pli and BAQHRBKT.pli and the standalone PL/I application BAQHRBKZ.pli.
• The RedbookApi directory contains the API requester Gradle sub-project, called from the outer Gradle build file.
• The RedbookApi/src/main/api directory contains the OpenAPI document, redbookapi.yaml, that describes the endpoint API application.
• The RedbookApi/src/main/config directory contains the options.yaml file used to control how the redbookapi.yaml file is processed to produce a z/OS Connect API requester WAR file.
• The RedbookApiPLI directory contains the API requester Gradle sub-project, called from the outer Gradle build file.
• The RedbookApiPLI/src/main/api directory contains the OpenAPI document, redbookapi.yaml, that describes the endpoint API application.
• The RedbookApiPLI/src/main/config directory contains the options.yaml file used to control how the redbookapi.yaml file is processed to produce a z/OS Connect API requester WAR file.
• The src/main/java/com/ibm/zosconnect/redbook/app directory contains the RedbookApp Java class that implements a JAX-RS Application for the endpoint application.
• The src/main/java/com/ibm/zosconnect/redbook/model directory contains the Java classes that represent the OAS schemas from redbookapi.yaml.
• The src/main/java/com/ibm/zosconnect/redbook/resource directory contains the Java classes used to implement the operations defined in redbookapi.yaml.
• The src/main/webapp/WEB-INF directory contains the web.xml file required for the Redbook endpoint application.

RedbookAPI operations

getAllRedbooks

Path /redbooks. Method GET. Passes an optional author query parameter of type string and expects an array of Redbook objects for a 200 response.

getRedbook

Path /redbook/{bookName}. Method GET. Passes a title path parameter, and optional author query parameter and optional documentType header parameter. A Redbook object is returned for a 200 response. For a 404 (Not Found) response a RedbookNotFound object is returned containing a message. A 500 for media type text/plain with a string schema.

createRedbook

Path /redbook/{bookName}. Method POST. Passes a bookName path parameter and a Book object body. Expects a Book object for a 2XX wildcarded response. A 409 (Conflict) can also be returned. No other default responses are defined.

Application Component Schemas

Redbooks

An array schema type with items as the Redbook schema.

Redbook

An object schema with properties relating to IBM Red Book metadata.

RedbookNotFound

A simple object schema with a String message used to denote a Redbook is not found and an array of Redbook objects that the supplied author has written.

CICS Resources

BAQHRBKC CICS COBOL or PL/I program

The CICS COBOL program BAQHRBKC.cbl, or the CICS PL/I program BAQHRBKC.pli is called for three transactions that then call the three different operations on the remote API endpoint.

CICS CSD BAQHRBKD

A CSD update file to define the Transactions and Program definitions into group BAQHRBKG.

IMS Resources

BAQHRBKB and BAQHRBKT IMS COBOL or PL/I programs

The IMS COBOL program BAQHRBKB.cbl, or the IMS PL/I program BAQHRBKB.pli is an IMS Batch application that can call one of the three RedbookAPI operations depending on the operation short code (GARB, GRBK or CRBK) passed to the program. The operation short code is passed in through the IMS APARM JCL statement.

The IMS COBOL program BAQHRBKT.cbl, or the IMS PL/I program BAQHRBKT.pli is an IMS Transactional application that can call one of the three RedbookAPI operations depending on the operation short code (GARB, GRBK or CRBK) passed to the program. The desired operation short code is passed in through the message segment data when the transaction is invoked.

Standalone Resources

BAQHRBKZ COBOL or PL/I program

The COBOL program BAQHRBKZ.cbl, or the PL/I program BAQHRBKZ.pli can call one of the three RedbookAPI operations depending on the operation short code (GARB, GRBK or CRBK) passed to the program as a PARM value via JCL.

License

See LICENSE for details.