Developing APIs with Gradle

You can develop APIs starting with an OpenAPI 3.0 definition and use the IBM z/OS Connect API provider Gradle plug-in to generate the API provider project files and the language copybooks that are required to implement the API.

From z/OS Connect V3.0.69.0, the supplied Gradle plug-in can be used to generate a complete API provider project, which can then be built and deployed into z/OS Connect. These APIs are then used to call your CICS® COBOL or PL/I channel and container applications.

See System requirements for the supported releases of the API provider Gradle plug-in

Figure 1. Building API provider API with the Gradle plug-in
With an API specification as input, the Gradle build creates all the API artifacts
Note: The API project that is generated by the API provider Gradle plug-in cannot be loaded by the z/OS Connect Designer.
A generated API provider project contains all the information about the API required to run it in z/OS Connect. This includes:
  • An API Project that can be included in the build of an IBM z/OS Connect API image, which can be deployed to a container platform of your choice.
  • Each API operation path in the original OpenAPI 3.0 definition and its associated request and response code mapping.
  • The z/OS Assets required to call the z/OS program implementing the API and to transform the request and response data structures.
To create an API provider project, you must first obtain an existing OpenAPI 3.0 definition that describes the API to be implemented.
An API provider project is then created by generating the artifacts for an API provider by using the API provider Gradle plug-in and the OpenAPI 3.0 definition. The Gradle build generates the following artifacts:
  • A complete API provider project, which can be used to build a IBM z/OS Connect API image, which can be deployed to a container platform of your choice.
  • A WAR file that can, alternatively, be deployed into an z/OS Connect native server to activate the API provider.
  • COBOL copybooks or PL/I include files that are used in the z/OS applications to read the API request data, implement the API logic, and construct the API response data.
When the COBOL copybooks or PL/I include files are created, you can use them to develop the z/OS application that will implement the API.

In addition to creating your API provider, you should also establish connections between z/OS Connect server and the z subsystem. For more information about establishing connections to CICS, see Configuring an IPIC connection to CICS.

Figure 2. Establishing a connection to the z/OS Connect server and the z subsystem
Establishing a connection the z/OS Connect server and the z subsystem