Creating and deploying the API requester tutorial

Use this tutorial to understand how to call an OpenAPI 3.0 API endpoint from your z/OS applications.

zosConnect-3.0 Applies to zosConnect-3.0.

Started task Applies to z/OS Connect Servers run by using a z/OS started task procedure.

This tutorial demonstrates the IBM z/OS Connect API requester tutorial project structure and how to download the files that contain the Gradle project, ready for deployment to a z/OS Connect Server with the zosConnect-3.0 feature.

The API requester tutorial includes an OpenAPI 3.0 document. From 3.0.99, z/OS Connect supports generating an API requester from either an OpenAPI 2.0 document or OpenAPI 3.0 document when deploying to a z/OS Connect Server with the zosConnect-3.0 feature. This tutorial project is based on an OpenAPI 3.0 document

Important: This tutorial assumes that the project is expanded to a PC-type system.

Downloading the tutorial

How to download the z/OS Connect API requester sample-oas3-requester project for this tutorial.

Before you begin

Make sure that the following requirements are met:

Procedure

  1. Download the z/OS Connect API requester sample project from A launch icon to indicate a link opens a new tab or window. https://github.com/zosconnect/sample-oas3-requester by using one of the supported methods as shown in the following image.
    Figure 1. Download the methods in GitHub
    Screen capture to show the various download methods in GitHub: HTTPS, SSH, GitHub CLI.
    Note: If you do not have access to GitHub, then the sample is provided as a .zip file in the product installation at <installation_path>/samples/apiRequester/com.ibm.zosconnect.apirequester.sample.zip.

    This .zip file contains a Gradle project that you can import to your integrated development environment, or expand to your PC or Laptop, or expand to z/OS UNIX System Services.
  2. Understand the sample-oas3-requester project structure.

    The sample-oas3-requester project includes the Gradle files: build.gradle, settings.gradle, and gradle.properties. These files control how the build process runs and what it builds.

    Additionally, the project contains a A launch icon to indicate a link opens a new tab or window. README file that provides an overview of the directory structure and summarizes its contents.

Building the tutorial by using Gradle

How to build the z/OS Connect API requester sample-oas3-requester tutorial by using Gradle.

About this task

This topic provides an overview of the project and the Redbook OpenAPI 3.0 document and options.yaml, the build inputs, outputs, and details on how to run the build to generate the API requester.

The z/OS Connect API requester sample contains the necessary Gradle automation build files to create the API endpoint application WAR file by compiling the Java™ source code and packaging the WAR file for deployment into Liberty. The Gradle build also starts a sub Gradle build in the RedbookApi and RedbookApiPLI directories that create the z/OS Connect API requester WAR files by processing the redbookapi.yaml OpenAPI 3.0 document and associated options.yaml file.

The z/OS Connect API requester sample also contains COBOL and PL/I program source files that call the z/OS Connect API requester Host API. These are provided in different degrees of completeness depending on whether you want to start the project from scratch, or access the completed working programs. The completed programs are in the finish subfolder of the COBOL and PL/I sub directories. Alternatively, if you want to learn, the start subfolder. For more information about the project structure, see the A launch icon to indicate a link opens a new tab or window. README file that summarizes the project directory content and structure. For more information on this Gradle build function, see Building an API requester WAR file.

Build inputs

For the endpoint application WAR file, the Java code that is located in src/main/java is compiled and packaged with src/main/webapp/WEB-INF/web.xml to create the API endpoint application WAR file redbook-1.0.0.war. For more information on how to deploy the WAR file to a running server, see Deploying an API requester WAR file.

To create the z/OS Connect API requester WAR file, the files at RedbookApi/src/main/api/redbookapi.yaml and RedbookApi/src/main/config/options.yaml are used by the z/OS Connect API requester Gradle plug-in to build the mapping and transformation information. This information is used within z/OS Connect to process a request and to call the API endpoint application, transforming binary data to and from JSON with the correct parameter settings and bodies for the API to function.

The sample mapping and transformation information are packaged in the RedbookApi.war file. For more information on how to deploy the WAR file to a running z/OS Connect Server, see Deploying an API requester WAR file.

Redbooks OpenAPI 3.0 document

The redbookapi.yaml file describes an OpenAPI 3.0 API with two paths and five operations. An operation is defined as a unique callable endpoint of the application API and the five operations in the sample API are getAllRedbooks, getRedbook, createRedbook, patchRedbook, and mergeRedbook. For more information about the RedbookAPI operations, see the A launch icon to indicate a link opens a new tab or window. README file.

For more information about the redbookapi OpenAPI 3.0 document, see the OpenAPI 3.0 specification that is described at A launch icon to indicate a link opens a new tab or window. What is OpenAPI?

options.yaml file
The z/OS Connect API requester Gradle plug-in processes the redbookapi.yaml file to produce the mapping and transformation information. To determine how this transformation takes place, the options.yaml file has several parameters that control the generated artifacts such as names, versions, and how the COBOL data structures are transformed to and from JSON. Only the language option is required. The other parameters are optional. For a complete description of the parameters, see The API requester Gradle plug-in properties and options.
The options.yaml defines.
language: COBOL
Used to define the type of language used.
requesterPrefix: RBK
Used to define the prefix to generated language structures. The default is API.
defaultCharacterMaxLength: 50
Used to set any OAS string type to a maxLength of 50. If maxLength is not defined, the default is 255.
defaultFractionDigits: 2
Used to define how many fraction digits to use for type number fields of the format decimal.

Procedure

  1. Ensure that you have a JAVA_HOME environment variable set to locate the home directory of a JDK installation on your system.
  2. From within the project directory, enter the Gradle command. 
    gradle build --info

    This command runs the build.gradle file to produce the two WAR files to run the sample. For more information, see Generating the language structures for an API requester.

    If running under z/OS UNIX System Services, reference the topic Building IBM z/OS Connect APIs with Gradle that explains how to run Gradle on z/OS.

  3. The Gradle build completes with BUILD SUCCESSFUL.

    If it isn't successful, review the Gradle build log and also the Gradle plug-in log files. If the cause of the problem isn't obvious, see Troubleshooting.

What to do next

Understand the build output. The Gradle build produces two WAR files. One for the API endpoint application and one for the z/OS Connect API requester. The following list details the build outputs for the sample-oas3-requester start tutorial.

redbook-1.0.0.war
The API endpoint application contains the compiled Java classes and a web.xml file in a format that conforms to WAR file standards and can be deployed to Liberty. This WAR file is created in the project's build/libs directory.
RedbookApi.war
The z/OS Connect API requester contains a web.xml file and conforms to WAR file standards and can be deployed to a z/OS Connect Server instance. The WAR file contains mapping and transform files for each operation. This WAR file is created in the project's RedbookApi/build/libs directory.
RedbookApiPLI.war
The z/OS Connect API requester for PL/I applications contains a web.xml file and conforms to WAR file standards and can be deployed to a z/OS Connect Server instance. The WAR file contains mapping and transform files for each operation. This WAR file is created in the project's RedbookApiPLI/build/libs directory.
COBOL copybooks for each operation that is defined in the redbookapi.yaml file
Under RedbookApi/build/generated/zosConnectRequester/structures/COBOL are the COBOL copybooks for each operation that is defined in the redbookapi.yaml file. These must be copied to a suitable PDS on z/OS that is referenced in your COBOL compile JCL.
PL/I include files for each operation that is defined in the redbookapi.yaml file
Under RedbookApiPLI/build/generated/zosConnectRequester/structures/PLI are the PL/I include files for each operation that is defined in the redbookapi.yaml file. These PL/I include files must be copied to a suitable PDS on z/OS that is referenced in your PL/I compile JCL.
Parser processing log files
The parser processing log files are located in RedbookApi/build/logs and RedbookApiPLI/build/logs.

Creating a z/OS Connect Server to deploy the sample-oas3-requester sample

How to create a z/OS Connect Server with the zosConnect-3.0 feature to deploy the API requester sample-oas3-requester start tutorial.

Before you begin

The following tasks must be completed.

About this task

This task takes you through the steps to create and deploy a sample z/OS Connect Server to run the tutorial. After creation, the sample server contains both the API requester WAR file and the API endpoint WAR file. However, you can optionally update both these WAR files if you change the tutorial source files.

For more information, see Deploying API requesters to IBM z/OS Connect.

Procedure

  1. Create an API requester sample server.
    Use the following command to create an API requester tutorial sample server with the provided server template sampleApiRequesterRedbooks that is at <installation_path>/runtime/templates/servers:
    <installation_path>/bin/zosconnect create server1 --template=zosconnect:sampleApiRequesterRedbooks
    For more information about z/OS Connect Server templates, see Supplied server templates.
  2. Edit the template server.xml.
    By default server1 listens on port 9080 for HTTP connections. To specify the new port number, you need to edit the server.xml and modify the httpEndpoint and zosconnect_endpointConnection elements.
    Note:
    • Use the same port number in both XML elements.
    • For CICS, make sure that the URIMAP defined to CICS for the z/OS Connect Host API, BAQHZCON by default, specifies the same IP address and port of the sample tutorial server.
  3. Start the z/OS Connect Server.
    The sample tutorial server is now ready to be started. For more information, see Starting and stopping the IBM z/OS Connect Servers.
  4. Optional: Update the API requester and API endpoint WAR files. When you update the source project, causing the WAR files to be regenerated, you can redeploy them to the z/OS Connect Server.

What to do next

Run the CICS application or z/OS application as part of the z/OS Connect API requester tutorial. Choose one of the following tasks: