Developing z/OS applications to call APIs
You can develop z/OS applications to call OpenAPI 3.0 defined APIs.
- Include the necessary data structures.
- Prepare the data for the API request.
- Call the Host API callable interface.
- Handle the response.
Before you begin
- 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
For more information about the Host API verbs, required data structures, and concepts, see the Understanding the Host API.
|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||77 Levels 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 IBM 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 IBM z/OS Connect with the response JSON body and any headers that are produced by the RESTful API endpoint operation.|
- 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,
- nn is an ordinal two-digit number, starting at 00, with a value per operation within the OpenAPI definition.
- The prefix
APIis the default and can be changed by setting the
requesterPrefixoption in options.yaml file. For example,
requesterPrefix: RBKproduces a copybook that is named
The copybooks that are provided by IBM z/OS Connect are available in data set hlq.SBAQCOB. The generated copybooks are located within the Gradle build project.
What to do next
The following sections describe the IBM z/OS Connect Host API interface and the steps to call OpenAPI 3.0 defined RESTful APIs from your z/OS applications.