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.

zosConnect-2.0 Applies to zosConnect-2.0.

Started task Applies to z/OS Connect Servers run by using a z/OS started task procedure.

Based on an OpenAPI 2.0 document (also known as 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.

From 3.0.99, consider using the zosConnect-3.0 feature when your API is described by an OpenAPI 2.0 document. You can continue to use the zosConnect-2.0 feature. However, the zosConnect-3.0 feature supports more features as detailed in ../oa3/api_requester.html#apirequester__table_additional_apireq_oa3. If you have an OpenAPI 3.0 document, you must use the zosConnect-3.0zosConnect-3.0 feature when your API is described by an OpenAPI 2.0 document. You can continue to use the zosConnect-2.0 feature. However, the zosConnect-3.0 feature supports more features as detailed in ../oa3/api_requester.html#apirequester__table_additional_apireq_oa3. If you have an OpenAPI 3.0 document, you must use the zosConnect-3.0 feature.

The following table shows the generated artifacts and their functions for an OpenAPI 2.0 specification API requester deployed to a z/OS Connect Server that is configured with the zosConnect-2.0 feature.

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 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 that are defined in this 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 that 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.
- Arrays that specify a value of 1 for the minItems and maxItems properties will generate a single object, not a single-element array that encapsulates that object.