Developing an API requester

Your z/OS applications can call OpenAPI 2.0 APIs and OpenAPI 3.0 APIs, with JSON payloads, through IBM® z/OS Connect.

Started task Applies to z/OS Connect Servers run by using a z/OS started task procedure.

Before you begin, make sure you're familiar with the fundamentals of z/OS Connect API requesters. For more information, see What are z/OS Connect API requesters?

When using the zosConnect-3.0 feature, the z/OS application that you develop uses the zosConnect-3.0 Host API to call the API requester that is deployed in the z/OS Connect Server. This in turn calls the REST API. The same flow applies when using the zosConnect-2.0 feature but the z/OS Connect communication stub is used to call the API requester instead of the Host API. The Host API and communication stub have different interfaces, so an application developed to call the communication stub cannot be simply reused to call the Host API. The API requester that you build is of a different format depending on whether you are deploying it to a z/OS Connect Server with the zosConnect-3.0 or zosConnect-2.0 feature. It contains information about the API and defines how COBOL or PL/I language structures are mapped to the API request and response.

Choosing between the zosConnect-2.0 and the zosConnect-3.0 feature for API requesters

From 3.0.99, consider using the zosConnect-3.0 feature when your API is described by an OpenAPI 2.0 document. You can continue to use the zosConnect-2.0 feature. However, the zosConnect-3.0 feature supports extra functionality as detailed in Table 1. If you have an OpenAPI 3.0 document, you must use the zosConnect-3.0 feature.

The zosConnect-3.0 zosconnect:oasRequester-1.0 feature comes with extra functionality in support of OpenAPI 2.0 and OpenAPI 3.0 APIs that are detailed in the following table.

Table 1. zosConnect-3.0 API requester extra functionality
Extra functionality Description
Data Areas When the OpenAPI 2.0 document or the OpenAPI 3.0 document has large unbounded arrays, Data Areas can be used to dynamically allocate the working storage that is required to access them. This reduces the memory requirements for the application program and prevents transferring large amounts of null data between the application program and z/OS Connect. For more information about Data Areas, see Understanding the Host API.
Multiple response codes Operations that are defined in the OpenAPI 2.0 document or the OpenAPI 3.0 document that return multiple response codes are now supported. At runtime, the z/OS application can detect which HTTP response code is returned by the API endpoint and then access the Data Area that is associated with the response code. For more information about Data Areas, see Understanding the Host API.
SAF-based security API requester authorization is configured by using SAF EJBROLE profiles to define the SAF users and groups that have the authority to invoke the API requester. For more information, see API requester authorization.
Operation filtering The API requester Gradle plug-in allows operation filtering so that only a subset of the operations in an OpenAPI 2.0 document or an OpenAPI 3.0 document are exposed to the calling application program.
API endpoint change toleration An API requester WAR file does not need to be rebuilt if the remote API is updated to return more data fields. If fields are removed, the API requester WAR file must be rebuilt.
Multiple API requesters Multiple API requesters can be deployed to a single z/OS Connect Server for a single API endpoint.
additionalProperties From 3.0.87, the additionalProperties flag in the request and response schemas for API requesters allows for dynamic properties that are not formally described to be used during the life of the API. For more information, see Using additionalProperties.
PATCH From 3.0.87, the REST resource can be partially updated by using the REST API PATCH HTTP method (RFC6902, RFC7396). For more information, see Using the PATCH HTTP method in an application.
TMRA From 3.0.98, an additional transport option for API requester scenarios between IMS and z/OS Connect is supported. If your IMS application requires POSIX(OFF), you can now use the IMS TM Resource Adapter instead of the IBM Web toolkit to connect to a z/OS Connect Server. For information, see Configuring IMS to access IBM z/OS Connect to call APIs.
OpenAPI 2.0 document support From 3.0.99, support for OpenAPI 2.0 specification API requesters with a z/OS Connect Server that is configured with the zosConnect-3.0 feature.