Developing API provider with zosConnect-3.0

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.

z/OS Connect provides two methods for you to create APIs from an OpenAPI 2.0 document or an OpenAPI 3.0 document. The Meet-in-the-middle method and the API-first method, which is also known as the top-down method.
Meet-in-the-middle

If you have an OpenAPI 2.0 document or an OpenAPI 3.0 document and the language structures, the IBM z/OS Connect Designer provides a containerized development and test environment in which to build and test your OpenAPI 3.0 specification API.

The z/OS Connect Designer is a code-based, containerized, intuitive web-based tool that has its own built-in development server for building and testing an API project. z/OS Connect Designer runs on a local development machine or in a cloud-native environment.

API-first

If you only have an OpenAPI 2.0 document or an OpenAPI 3.0 document, you can use either the z/OS Connect API provider Gradle plug-in or the IBM z/OS Connect development tools for Visual Studio Code to generate the API project files and the language structures to implement the API.

Note:
  • Customers with an existing z/OS Connect OpenAPI 2.0 API deployed on a server that is configured with the zosConnect-2.0 feature can easily transition to the zosConnect-3.0 feature using the API provider Gradle plug-in. By providing the OpenAPI 2.0 document, the plugin automatically generates the necessary API project files and language structures. The COBOL or PL/I application that implements the API must be created or updated to incorporate the newly generated language structures. The resulting WAR file can then be deployed to a new server configured with the zosConnect-3.0 feature. Importantly, no changes are required to existing client applications that consume the API.
  • If the API provider is generated from an OpenAPI 2.0 document, consider using the zosConnect-3.0 feature that supports richer mapping, open telemetry and much more.

Both the z/OS Connect API provider Gradle plug-in and the IBM z/OS Connect development tools for Visual Studio Code extension create the z/OS Connect API provider language structures with which you can develop a z/OS applications to implement the API defined in the OpenAPI 3.0 document.

The IBM z/OS Connect development tools for Visual Studio Code extension includes syntax highlighting and information popups providing an intuitive user experience with real-time assistance when developing z/OS applications to implement an API. However, the extension doesn't build the API project WAR file. The z/OS Connect API provider Gradle plug-in must be used to build the API project WAR file by using the steps in the Using Gradle to build the API project. If you are working offline in an airgap (disconnected) environment, there are details on using Gradle to build the API project WAR file at Using Gradle in an offline (airgapped) environment.

Important:
zosConnect-3.0 artifacts (WAR files), can be deployed in a z/OS Connect Server that is a container image or a started task that is at the same release level or later than the release level of the z/OS Connect Designer or z/OS Connect Gradle plug-ins that were used to generate the artifacts. For more information, see z/OS Connect artifact compatibility.
Restriction: zosConnect-3.0 artifacts (WAR files) should not be deployed to a z/OS Connect Server that is a container image or a started task that is an older release version than the release version of the z/OS Connect Designer, the z/OS Connect API provider Gradle plug-in or the z/OS Connect API requester Gradle plug-in.

For a step-by-step tutorial to generate the API project artifacts by using the API provider Gradle plug-in and to develop a z/OS application for the API provider to call the API endpoint, see Creating a subsystem z/OS Connect API provider project.