Generating the language structures for an API requester

Use the API requester Gradle plug-in with an OpenAPI 2.0 document or an OpenAPI 3.0 document (described in JSON or YAML) to generate the API requester artifacts to deploy on a z/OS Connect Server with the zosConnect-3.0 feature. The zosConnect-3.0 API requester feature is zosconnect:oasRequester-1.0.

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 requester artifacts generated as part of the Gradle build enable your z/OS applications to call REST APIs. In addition to the API requester Gradle plug-in, you can also use the z/OS Connect development tools for Visual Studio Code extension to generate the language data structures for your API requester application. For more information, see Installing the IBM z/OS Connect development tools for Visual Studio Code extension. When using the z/OS Connect development tools for Visual Studio Code extension to generate the language data structures, the API requester Gradle plug-in must be used to generate the WAR file.

Table 1 shows the generated artifacts for an API requester and their functions:
Table 1. Generated artifacts for an API requester and their functions
Generated artifact Function Tooling
API requester archive file (WAR) An archive file that can be deployed into an z/OS Connect Server. It contains the transformations that z/OS Connect Server uses to convert the request payload from binary format to JSON format and convert the response payload from JSON format to binary format.
  • API requester Gradle plug-in
Language structures Request data, response data, and API information structures that are generated for each operation in the API.

The API information structure contains variables that are used by z/OS applications when they call the API. The values for these variables are populated automatically based on the OpenAPI document.
  • z/OS Connect development tools for Visual Studio Code
  • API requester 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 document. A link to the folder that contains the logs is provided in the Gradle output.
  • API requester Gradle plug-in
Note:
  • A supported version of Gradle on the build or development machine where the z/OS Connect API requester WAR file is generated. For more information about supported Gradle versions, see IBM z/OS Connect system requirements.
  • The OpenAPI 2.0 document or OpenAPI 3.0 document must be encoded in UTF-8.
  • z/OS Connect supports JSON media types that comply with the OpenAPI 3.0 specification.
  • The Gradle plug-in can process most of the Open API 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.
    • Mixed-Type arrays are not supported.

When generating API requester artifacts from an OpenAPI 2.0 document for an API requester that is deployed on a z/OS Connect Server with the zosConnect-3.0 feature, some build toolkit configuration options have been replaced by the API requester Gradle plug-in and Host API functions. The replaced options are detailed as follows:

  • defaultArrayMaxItems - Not required in zosConnect-3.0 feature. The zosConnect-3.0 feature uses the Host API to allow z/OS application to communicate with z/OS Connect Server. Host API supports the concept of Data Areas for receiving dynamically sized arrays.
  • addLanguageSuffix - Not required in zosConnect-3.0 feature. The API requester Gradle plug-in has an apiName configuration option that serves the same purpose.
  • ignoreMIMETypeCheck and useMIMEType - With the zosConnect-3.0 feature, the content and MIME types are mandatory, replacing consumes and produces from the from the OpenAPI 2.0 document.
  • contentTypeForEmptyRequest - Not a supported property in the API requester Gradle plug-in. An OpenAPI 2.0 document with no request body is converted to the OpenAPI 3.0 specification with the MIME type set as application/json. That is, when z/OS Connect calls the API endpoint the request is sent with Content-Type application/json.

To generate the API requester language structures from your OpenAPI 2.0 document or your OpenAPI 3.0 document with the API requester Gradle plug-in, complete the procedure detailed at Using the API requester Gradle plug-in.

To generate the API requester language structures from your OpenAPI 2.0 document or your OpenAPI 3.0 document with the IBM z/OS Connect development tools for Visual Studio Code, complete the procedure detailed at Using the IBM z/OS Connect development tools for Visual Studio Code for an API requester project.