Using the build toolkit to generate artifacts for an API requester

You can use the build toolkit either from the command line interface or with the SDK.

Based on a Swagger document that is described in JSON or YAML format, you can use the build toolkit to generate all the artifacts to enable your z/OS® application to call an API.

The following table 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
API requester archive file (.ara) An archive file that can be deployed into the IBM® z/OS Connect run time. It contains the transformations so that IBM z/OS Connect can convert the request payload from binary format to JSON format and convert the response payload from JSON format to binary format.
API information file A data structure that contains variables that z/OS applications use when calling an API. Values of these variables are populated automatically based on the Swagger file to specify the name, path and method of an operation in the API. The data structure is generated for each operation in the API.
Data structure Request and response data structures that are generated for each operation in the API.
Log A log file for each operation defined in Swagger.
Summary report A log file for each API that logs all the operations and generated artifacts of each API.
Note:
  • The Swagger file must be encoded in UTF-8.
  • The build toolkit can process most of the Swagger 2.0 fields and objects except the following limitations:
    • Limited combinations of type and format are now supported. For more information, see JSON schemas supported by the build toolkit.
    • $ref defined in path is not supported.
    • Parameters defined in form are not supported.
    • Data transformation is not applied to the response with a non-2xx response code. The response body is directly returned to the z/OS application.
    • If more than one 2xx response codes are defined in one operation, only the response data with the minimum response code can be transformed.
    • $ref to a file is not supported.
    • Fields of consumes or produces that are populated with values containing no application/json are not supported.
    • 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 -_.!',;:@=&%$+*( and ).
      • Characters that are accepted but will be 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 -_.!,'%{};:@= and &.
    • Arrays that are wrapped up with more than 7 layers are not supported.