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. In the start folders of COBOL and PLI you will find the partial implementations, not all operations are coded, as an exercise you can complete the code. Should you wish to view the completed samples review the code in the finish folders.

The Patch and Merge operations are complete in both the start and finish versions of the code samples. Please refer to the IBM Patch documentation to assist in understanding the code.

Structure

• The COBOL/finish directory contains the CICS COBOL program BAQHRBKC.cbl, IMS COBOL programs BAQHRBKB.cbl and BAQHRBKT.cbl and the standalone COBOL application BAQHRBKZ.cbl. These programs have all three operations implemented.
• The COBOL/start directory contains the CICS COBOL program BAQHRBKC.cbl, IMS COBOL programs BAQHRBKB.cbl and BAQHRBKT.cbl and the standalone COBOL application BAQHRBKZ.cbl. These programs have only one of three operations implemented.
• The COPY directory contains all required COBOL copybooks. Those that are generated by building the RedbookApi requester project, those that are shipped with z/OS Connect and one 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 all required PL/I include files. Those that are generated by building the RedbookApiPLI requester project, those that are shipped with z/OS Connect and one for IMS related constants, functions and data structures.
• The PLI/finish 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. These programs have all three operations implemented.
• The PLI/start 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. These programs have only one of three operations implemented.
• 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/{title}. 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.

patchRedbook

Path /redbook/{title}. Method PATCH. An RFC 6902 compliant patch request. Passes a bookName path parameter and a RFC 6902 Patch document. Expects a Book object for a 200 response. For a 404 (Not Found) response a RedbookNotFound object is returned containing a message.

mergeRedbook

Path /redbook/m/{title}. Method PATCH. An RFC 7396 compliant patch request. Passes a bookName path parameter and a RFC 7396 Patch document. Expects a Book object for a 200 response. For a 404 (Not Found) response a RedbookNotFound object is returned containing a message.

Application Component Schemas

Redbooks

An array schema type with items as the Redbook schema.

Redbook

An object schema with properties relating to IBM Redbook 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.

Understanding the Redbook information API endpoint application

This Redbook API requester sample demonstrates a simple IBM Redbook information application, called com.ibm.zosconnect.redbook.app. The application is implemented in Java and hosted in Liberty. com.ibm.zosconnect.redbook.app is a JAX-RS Java™ application that receives REST requests with parameters and JSON request payloads, and returns responses in JSON format. It supports three operations defined in the redbookapi.yaml OpenAPI 3.0 document.

The application is constructed from the following classes:

• RedbookApp.java
  • This is a JAX-RS Application instance that defines the Path processing resource classes.
• Author.java
  • A model class that represents a single Author of a Redbook.
• OwningDepartment.java
  • A model class that represents the department that owns the Redbook.
• Redbook.java
  • A model class that represents the OpenAPI schema Redbook and contains the data instances for that schema.
• RedbookNotFound.java
  • A model class that represents the OpenAPI schema RedbookNotFound and contains the data instances for that schema.
• RedbooksResource.java
  • A JAX-RS class that accepts a GET method on Path /redbooks that starts method getAllRedbooks and returns an array of Redbook model objects. JAX-RS converts the Redbook model objects to JSON. This class also acts as the data repository for the RedBook inventory. This inventory is a Map of 10 Red Books. There is also a secondary Map of Red Books written by the same author.
• RedbookResource.java
  • A JAX-RS class that the process requests to /redbook/{title} for methods GET and POST. These start methods getRedbook and createRedbook use the Redbook model class and RedbookNotFound model class. The Redbook inventory is acquired from class RedbooksResource.

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.