Generating the language structures for an API provider

Use the API provider Gradle plug-in or IBM® z/OS® Connect development tools for Visual Studio Code extension with an OpenAPI 2.0 document or an OpenAPI 3.0 document (described in JSON or YAML) to generate and build the API provider artifacts to deploy into IBM z/OS Connect.

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.

API provider artifacts that are generated as part of the Gradle build are used to expose your z/OS applications as REST APIs. In addition to the API provider Gradle plug-in, you can also use the z/OS Connect development tools for Visual Studio Code extension to generate the language structures for your API project. When using the z/OS Connect development tools for Visual Studio Code extension to generate the language structures, the API provider Gradle plug-in must be used to generate the WAR file. For more information about the IBM z/OS Connect development tools for Visual Studio Code extension, see Using the IBM z/OS Connect development tools for Visual Studio Code for an API project.

Table 1 shows the generated artifacts for an API provider and their functions:
Table 1. Generated artifacts and their functions for an API provider
Generated artifact Function Tooling
API provider archive file (WAR) An archive file that can be deployed into an z/OS Connect Server. It contains the API operations and transformations that z/OS Connect uses to convert the request payload from JSON format to binary format and convert the response payload from binary format to JSON format.
  • API provider Gradle plug-in
Language structures Request and response structures that are generated for each operation in the API. These structures are used by the called program to implement the API by processing the request and response data.
  • z/OS Connect development tools for Visual Studio Code
  • API provider Gradle plug-in
Logs When the Gradle build is run with the --info option, a log file is generated in addition to the Gradle output for each operation defined in the OpenAPI definition. A link to the folder that contains the logs is provided in the Gradle output.
  • API provider Gradle plug-in
Note:
  1. A supported version of Gradle must be installed on the build or development machine where the z/OS Connect API provider WAR file is generated. For more information, see IBM z/OS Connect system requirements.
  2. The OpenAPI 2.0 document or the OpenAPI 3.0 document must be encoded in UTF-8.
  3. z/OS Connect supports JSON media types that comply with the OpenAPI 2.0 specification or the OpenAPI 3.0 specification.
  4. The Gradle plug-in can process most of the OpenAPI fields and objects with the following limitations:
    • Not all the characters in the title and operation path of an API are accepted.
    • For the title of an API, characters that are accepted are uppercase characters (A-Z), lowercase characters (a-z), digits (0-9), and special characters -_.!',;:@=&%$+*(). Characters that are accepted but replaced with the hyphen character are #|\\ ^[]~`<>?/ and blanks.
    • For the operation path of an API, characters that are accepted are uppercase characters (A-Z), lowercase characters (a-z), digits (0-9), and special characters -_.!,'%{};:@=&

    • Arrays that are wrapped with more than seven layers are not supported.

To generate the API project artifacts from an OpenAPI 2.0 document or an OpenAPI 3.0 document, complete the steps given in Using the API provider Gradle plug-in. After the API project artifacts are generated, develop the z/OS application, establish the connection from the z/OS Connect Server to CICS and then deploy your API WAR file.