Generating artifacts for an API requester from the command line

Enter the zconbt command on the command line to generate the artifacts to call an API from your z/OS® application.

Before you begin

Ensure that the IBM® z/OS Connect build toolkit is installed. For more information, see Installing the IBM z/OS Connect build toolkit.
Prepare the Swagger file of the API that your z/OS application wants to call. The IBM z/OS Connect build toolkit uses the Swagger file as an input to generate artifacts to call the API. For more information about the Swagger file and the generated artifacts, see Using the build toolkit to generate artifacts for an API requester.

About this task

Follow these steps to use the IBM z/OS Connect build toolkit to generate the API information file, data structures, and API requester archive for a z/OS application to call a RESTful API. The following steps use an example of calling the Watson™ translator API from a COBOL application.

To learn more about the build toolkit, see The IBM z/OS Connect build toolkit.

For best results, generate the data structures on the z/OS platform directly. If you want to run the build toolkit on a non-z/OS platform, set a non-z/OS code page, such as UTF-8, by specifying the generatedCodePage property in the build toolkit properties file and upload the generated data structures to the z/OS data set in ASCII mode via FTP.

If you use EDCDIC when generating data structures on a non-z/OS platform and upload the data structures to a z/OS data set in Binary mode via FTP, the data structures might be corrupted because of the different newline characters in different platforms.

For more information about the generatedCodePage property, see The build toolkit properties file.

Procedure

Create directories to contain the generated artifacts from the build toolkit.

Based on the Swagger file that describes Watson translator API , you might create the directories as the following table shows:

Table 1. Directory paths and what they are created for
Path	What it is created for
./watson/	To store the Swagger file of the Watson translator API and the generated log file for each operation defined in the Watson translator API.
./watson/archives	To store the generated API requester archive file and the summary report for the Watson translator API.
./watson/structures	To store the generated data structures for each operation.
./watson/apiInfoFile	To store the generated API information file for each operation.

Create a properties file that is used as the input into the build toolkit.
The file contains name value pairs that include which Swagger file to use as input, the language of the data structures that are generated, and where the generated files are stored.
Here is an example of properties file based on the directories that were created in the previous step:
```
   apiDescriptionFile=./watson/watson_translator_v2.json
   dataStructuresLocation=./watson/structures
   apiInfoFileLocation=./watson/apiInfoFile
   requesterPrefix=API
   connectionRef=BluemixAPIConnect
   logFileDirectory=./watson
   language=COBOL
      
```
A description of the properties is provided in The build toolkit properties file.
Note:
- Ensure the Swagger file is encoded in UTF-8.
- The generated API requester archive is language specific. You must ensure the language that is specified in the properties file is the same as that used with your client z/OS application. For example, if the client z/OS application to call an API is developed in COBOL, you must specify the language attribute in the properties file as COBOL. Otherwise, an error occurs because the API requester archive is incompatible with your client z/OS application.
Use the zconbt command to generate API requester artifacts.

Use the --properties parameter to specify the properties file, and --file parameter to specify the file name for the generated API requester archive. For example:

zconbt --properties=watson.properties --file=./watson/archives/Watson.ara

Note: If you are running on Microsoft Windows, run the zconbt.bat command. If you are running on z/OS, run the zconbt.zos command.
If any errors occur, take the user action that is indicated in the error message to make the necessary corrections and repeat the procedure.

Results

Several artifacts for the API requester are created in the directories you have created. For each API, an API requester archive (.ara) file and a summary report are generated. For each API operation, an API information file, request data structures and response data structures are generated. The names of the generated request and response data structures and API information file are based on the requesterPrefix value that is specified in the properties file. For more information about the names of the generated artifacts, see Naming conventions for the API requester artifacts.

The following screen capture shows the expected API requester artifacts.

Diagram showing the API requester artifacts that are generated based on the directories that were created in the previous steps.

Figure 1. A screen capture of the expected API requester artifacts