Developing z/OS applications to call APIs

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

Before you begin

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.

Note: This section 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 IBM® 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 Understanding the Host API.

About this task

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 language structures.
Prepare the data for the API request.
Call the Host API callable interface.
Handle the response.

You can use either the z/OS Connect API requester Gradle plug-in or the IBM z/OS Connect development tools for Visual Studio Code extension to generate the API requester project artifacts and the language structures required to implement the API requester applications. 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. For more information, see Generating the language structures for an API requester.

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.

The COBOL program uses copybooks that are provided by z/OS Connect and also copybooks that are generated by the Gradle gradle apiRequesterLayoutcommand or the IBM z/OS Connect development tools for Visual Studio Code extension. For more information, see Generating the language structures for an API requester.

Table 1. Copybooks used by applications that call REST 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 REST 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 REST 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 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 REST API endpoint operation.

Note:

The BAQ-REQUEST-AREA is used to pass request parameters to z/OS Connect that are used to connect to the API endpoint operation. For example,
- Access 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 document.
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 COBOL 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.

The equivalent PL/I include files are provided by z/OS Connect are available in data set hlq.SBAQPLI with names BAQHAREP and BAQHCONP. The generated PL/I include files 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 API requester trace.

What to do next

The following sections describe the z/OS Connect Host API callable interface and the steps to call OpenAPI 2.0 and OpenAPI 3.0 specification REST APIs from your z/OS applications.