Developing APIs with API-first
You can develop OpenAPI 3.0 APIs for a z/OS Connect Server configured with the zosConnect-3.0 by using an OpenAPI 2.0 document or an OpenAPI 3.0 document. Use the IBM z/OS Connect development tools for Visual Studio Code extension or the IBM z/OS Connect API provider Gradle plug-in to generate the API project files and the language structures that are required to implement the API.
zosConnect-3.0 Applies to zosConnect-3.0.
From z/OS Connect 3.0.100, the
zosConnect-3.0 feature supports using an OpenAPI 2.0 document or an OpenAPI 3.0 document to develop OpenAPI 3.0 APIs by using the API-first
method.
- Customers with an existing z/OS Connect
OpenAPI 2.0 API deployed on a server that is
configured with the
zosConnect-2.0feature 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.
From z/OS Connect 3.0.97, the IBM z/OS Connect development tools for Visual Studio Code extension can be used to generate the API project artifacts. The IBM z/OS Connect development tools for Visual Studio Code extension doesn't generate the WAR file. This WAR file is generated by using the API provider Gradle plug-in by using the project artifacts that are generated by the IBM z/OS Connect development tools for Visual Studio Code extension.
From z/OS Connect 3.0.69, the supplied API provider Gradle plug-in can be used to generate a complete API 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 IBM z/OS Connect system requirements for the supported releases of the API provider Gradle plug-in.
API-firstby using the Gradle plug-in
To create an API project, you must first obtain an existing OpenAPI 2.0 document or an OpenAPI 3.0 document that describes the API to be implemented.
An API project is then created by generating the project artifacts from an OpenAPI 2.0 document or an OpenAPI 3.0 document. The API project artifacts can be generated by using either the API provider Gradle plug-in or the IBM z/OS Connect development tools for Visual Studio Code. The project artifacts that are developed by using the IBM z/OS Connect development tools for Visual Studio Code extension are built by using the API provider Gradle plug-in.
- An API project that contains all the information about the API required to run it including:
- Each API operation path in the original OpenAPI 2.0 document or the OpenAPI 3.0 document and its associated request and response code mapping.
- Language structures that are used in the z/OS applications to read the API request data, implement the API logic, and construct the API response
data.
This API project can be used to build the IBM z/OS Connect API image, which can then be deployed to a container platform of your choice.
- A
WARfile that can, alternatively, be deployed to a z/OS Connect Server run using a started task to act as the API provider.
When the language structures are created, you can use them to develop the z/OS application that implements the API.
In addition to creating your API provider, you should also establish connections between z/OS Connect Server and the CICS region. For more information, see Configuring an IPIC connection to CICS.
