What are z/OS Connect API requesters?
The IBM® z/OS Connect API requester feature enables COBOL and PL/I z/OS applications to call REST APIs at an API endpoint.
Started task Applies to z/OS Connect Servers run by using a z/OS started task procedure.
The z/OS Connect
API requester feature provides a unified approach
to incorporating published REST APIs into z/OS subsystems and
is supported on servers that run as a Started task. When using the zosConnect-2.0 feature, the API requester feature is
zosconnect:apiRequester-1.0. In 3.0.65, the API requester feature
zosconnect:oasRequester-1.0 was introduced for when using the zosConnect-3.0 feature. For more information about
z/OS Connect features, see z/OS Connect features.
z/OS Connect automatically converts the request payload from COBOL or PL/I binary format on input to JSON format. For the response from the RESTful endpoint, the output can be converted from JSON.
z/OS Connect can be configured to use payload compression to compress the JSON request body from the z/OS Connect Server to the API endpoint by using the gzip compression method and to accept a compressed JSON response body from the API endpoint.
z/OS Connect tooling starts with the OpenAPI document of the REST API to be called. From the OpenAPI document, it generates a deployable API requester artifact and either COBOL copybooks or PL/I include files (language structures) that can be used in a z/OS application to call the REST API.
Use the API requester Gradle plug-in with either an OpenAPI 3.0 document, or from 3.0.99 an OpenAPI 2.0 document, to generate an API requester WAR file that can be deployed into a server running the zosConnect-3.0 feature.
From 3.0.97, as an alternative to the Gradle plug-in, the IBM z/OS Connect development tools for Visual Studio Code can generate API requester WAR files from an OpenAPI 3.0 document. From 3.0.99, it can also do this for an OpenAPI 2.0 document.
Alternatively, use the build toolkit with an OpenAPI 2.0 (Swagger 2.0) document to generate an API requester archive (.ara) file that can be deployed into a server running the zosConnect-2.0 feature.
Comparison of the API requester features
The following table provides a summary of the API requester prerequisites, the generated API requester artifacts, and the associated configuration elements for the zosConnect-2.0 and zosConnect-3.0 features.
| zosConnect-2.0 zosconnect:apiRequester-1.0 | zosConnect-3.0 zosconnect:oasRequester-1.0 |
|---|---|
| Prerequisite: The OpenAPI 2.0 document (Swagger document) that describes the REST API that a z/OS application wants to call. | Prerequisite: The OpenAPI 2.0 document or the OpenAPI 3.0 document that describes the REST API that a z/OS application wants to call. |
| Generate: An API requester archive (.ara) for z/OS Connect to perform data mapping and transformation between z/OS Connect application language structures and JSON for calls to REST APIs. | Generate: An API requester WAR file for z/OS Connect to perform data mapping and transformation between JSON and language structures for HTTP API calls by z/OS applications. |
| Language structures that are used in the z/OS applications to construct the API request and read its response. | Language structures that are used in the z/OS applications to construct the API request and read its response. |
| Configure feature zosconnect:apiRequester-1.0 | Configure feature zosconnect:oasRequester-1.0. |
| Configure a zosconnect_endpointConnection element. | Configure a zosconnect_endpointConnection element. |
| Develop: The communication stub enables z/OS applications to call OpenAPI 2.0 specification APIs. | Develop: The Host API enables z/OS applications to call OpenAPI 2.0 and Open API 3.0 specification APIs. |
z/OS Connect API requester zosConnect-3.0
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.
Figure 1 shows how a z/OS application calls a REST API using the z/OS Connect Host API and API requester WAR file.
The Host API is the z/OS Connect zosConnect-3.0 feature equivalent of the zosConnect-2.0 communication stub. It enables z/OS applications to call OpenAPI 2.0 specification and OpenAPI 3.0 specification APIs.
For more information, see Developing an API requester.
For a step-by-step tutorial to call an OpenAPI 3.0 API endpoint from a CICS application, IMS, or a z/OS application, see Creating an IBM z/OS Connect API requester project and z/OS application.
z/OS Connect API requester zosConnect-2.0
zosConnect-2.0 Applies to zosConnect-2.0.
Figure 2 shows how a z/OS application calls a REST API using the communications stub and API requester archive file (.ara file).
For more information, see Developing API requesters with zosConnect-2.0.
For a step-by-step tutorial to call an API from a CICS application, IMS, or a z/OS application, see Calling an API from a System of Record (SoR).