Developing z/OS applications to call APIs

You can develop z/OS applications to call OpenAPI 3.0 defined APIs.

To communicate with the z/OS Connect Server and call an API endpoint, you must modify your z/OS application in four ways:

Include the necessary data structures.
Prepare the data for the API request.
Call the Host API callable interface.
Handle the response.

Before you begin

Use the API requester Gradle plug-in to generate the API requester artifacts, by following the instructions in Using the API requester Gradle plug-in. This action generates the z/OS Connect deployable API requester WAR file and a set of language structures per operation that is defined in the OpenAPI 3.0 definition. These language structures are used in the z/OS application along with a set of predefined language structures to call the Host API interface verbs.

Note:

For COBOL applications, the COBOL compiler option RTEREUS must be set to off as it is not supported when calling Host API verbs.
Compile your z/OS applications with the RENT option. This option is required by both z/OS Connect and the z/OS client web enablement toolkit.
Do not modify the generated language structures. If they are changed, they will not reflect the data that is returned from the API endpoint.

About this task

This topic discusses creating a COBOL application but, with a suitable syntax change, applies equally to PL/I.

Learn how to construct a COBOL program that uses z/OS Connect to call an API endpoint and transform COBOL language structures to and from JSON, or path or query parameters.

For more information about the Host API verbs, required data structures, and concepts, see the Understanding the Host API.

The COBOL program uses copybooks that are provided by z/OS Connect and also copybooks that are generated by the Gradle build. For more information, see Generating the artifacts for an API requester.

Table 1. Copybooks used by applications that call RESTful API operations
Copybook	Structure	Description
BAQHAREC	BAQ-ZCONNECT-AREA	Used to communicate the effectiveness of the verb, contains fields such as completion code, reason code, and return message. Can also contain parameters to affect the function of the Host API such as overriding the name of the CICS® URIMAP.
	BAQ-REQUEST-AREA	Contains the address and length of the BAQBASE request language structure, which is generated by the API requester Gradle plug-in. Can also contain parameters to specify request data such as credentials and parameters that are required to obtain OAuth 2.0 tokens or JWTs. See Note 1.
	BAQ-RESPONSE-AREA	Contains the address and length of the BAQBASE response language structure, which is generated by the API requester Gradle plug-in, and RESTful API endpoint HTTP status code and messages.
BAQHCONC		Constants used to map the Host API callable interface and parameter names.
APInnI01 Note 2, 3	BAQ-API-INFO-APInnI01	The BAQ-API-INFO-APInnI01 structure that is generated by the API requester Gradle build and is used by the application to pass details of the RESTful API operation to the Host API.
APInnQ01	BAQBASE-APInnQ01	The binary data structure that is generated by the API requester Gradle build. Used by z/OS Connect to pass data to the RESTful API endpoint operation in the form of path parameters, query parameters, and headers along with any JSON body.
APInnP01	BAQBASE-APInnP01	The binary data structure that is generated by the API requester Gradle build. Populated by z/OS Connect with the response JSON body and any headers that are produced by the RESTful API endpoint operation.

Note:

The BAQ-REQUEST-AREA is used to pass request parameters to IBM z/OS Connect that are used to connect to the API endpoint operation. For example,
- JSON Web Token parameters. For more information, see zosconnect_authToken access token-related parameters.
- OAuth 2.0 credential, resource, audience, and custom parameters. For more information, see zosconnect_oAuthConfig access token-related parameters.
nn is an ordinal two-digit number, starting at 00, with a value per operation within the OpenAPI definition.
The prefix API is the default and can be changed by setting the requesterPrefix option in options.yaml file. For example, requesterPrefix: RBK produces a copybook that is named RBKnnI01.

The copybooks that are provided by z/OS Connect are available in data set hlq.SBAQCOB. The generated copybooks are located within the Gradle build project.

You can use the Host API callable interface trace as an aid with your application development. For more information, see Enabling trace in the Host API Callable interface.

What to do next

The following sections describe the z/OS Connect Host API interface and the steps to call OpenAPI 3.0 defined RESTful APIs from your z/OS applications.