Understanding the Host API
The Host API callable interface is a replacement for the zosConnect-2.0 communication stub. It enables z/OS applications to call OpenAPI 2.0 specification and OpenAPI 3.0 specification APIs with the zosConnect-3.0 feature.
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.
The Host API provides an extended set of callable verbs to support the advanced features introduced in the OpenAPI 3.0 specification. For example, it can handle dynamically sized arrays and multiple mapped HTTP response codes from the API endpoint. This means the z/OS application can receive different response payloads based on the HTTP status code such as 200 (OK), 201 (Created), or 404 (Not Found). Each response payload that is defined in the OpenAPI 2.0 or OpenAPI 3.0 operation is mapped to a corresponding data structure in the generated language structure.
To enable these capabilities, the Host API uses Data Areas that are specific locations in program storage that hold data elements accessible sequentially by the z/OS application. Each dynamic array and each response code has its own Data Area. Managing these Data Areas, along with z/OS Connect connections, is handled through a set of Host API verbs that are collectively known as the Host API callable interface.
| Verb | Purpose |
|---|---|
| BAQINIT | Initialize the Host API and the connection to a z/OS Connect Server. |
| BAQPUTN | Add Data Elements that are defined by a generated language structure, to a request Data Area. |
| BAQEXEC | Make a request from the z/OS application to an HTTP API endpoint through z/OS Connect and receive the response. |
| BAQGETN | Reference a Data Area to get the next element from either a mapped response for the returned HTTP status code, or a dynamic array. |
| BAQFREE | Optional: Free Host API storage that is being used for Data Areas or was acquired during the call to BAQEXEC. |
| BAQTERM | Terminate the connection to the z/OS Connect Server and free all Host API storage. |
- Data Area names should be between 1 and 16 characters and consist of the following allowed
characters
A-Z a-z 0-9 $ @ # / % & ? ! : | " = , ; < > . - _ - Leading and embedded blank characters are not permitted in the name.
- If the name is fewer than 16 characters, it should be padded with trailing blanks up to 16 characters.
- The name must not start with the prefix
BAQ
.
The verbs in Table 1 use the following fixed-format language structures to control the function of the verb and to return its success or failure.
| Structure | Function |
|---|---|
| BAQ-ZCONNECT-AREA | Used to communicate the effectiveness of the verb, contains fields such as completion code, reason code, and return message. It can also contain parameters to affect the function of the Host API such as overriding the name of the CICS® URIMAP. |
| BAQ-API-INFO | Generated by the API requester Gradle plug-in, one per operation defined in the OpenAPI definition. Contains the API name and operation plus the API endpoint path and method. |
| BAQ-REQUEST-AREA | Contains the address and length of the BAQBASE request language structure that 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. |
| BAQ-RESPONSE-AREA | Contains the address and length of the BAQBASE response language structure that is generated by the API requester Gradle plug-in, and the API endpoint HTTP status code and messages. |
For more information about how to develop a z/OS application, see Writing an application that calls the Host API and the Getting started tutorials for IBM z/OS Connect zosConnect-3.0.