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

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.

To achieve a new line in the JSON string, a newline character (x'15 or x'25') in EBCDIC, must be provided. If "\n" in EBCDIC (x'E095') is used, it will be transformed into "\\n" in ASCII (x'5C5C6E') and not a new line character.

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

Procedure

  1. 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.
  2. 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.
  3. 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.
  4. 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