z/OS Connect - Group home

Calling a RESTful API from a CICS application

  

1. Introduction

This article describes how to call a remote API from a z/OS application. We use the CICS catalog manager example application and enhance it with a call to a remote API. We do not discuss security in this article but refer to the next article: ‘Use the OAuth support to call the OrderDispatch API’ for an implementation example using OAuth 2.0.

2. What is API Requester?

The API requester capability allows z/OS-based programs to access any RESTful endpoint, inside or outside the enterprise, for example a cloud-based microservice.
z/OS applications do not have to create the JSON payload nor they have to handle the HTTP request, z/OS Connect EE will manage these parts. The only modifications to the z/OS applications will be the initialization of the required fields in the generated copybooks and the call to the z/OS Connect communication stub program provided by z/OS Connect EE:

Figure 1: Architecture of z/OS Connect EE API requester

3. Example scenario

We describe an example scenario using the CICS catalog manager application.
More information on the application can be found here: The CICS catalog manager example application

This CICS example application is constructed around a simple sales catalog and order processing application, which is made of 3 operations:

  1. Inquire the catalog to list items from the datastore
  2. Inquire an item to get details about one item from the datastore
  3. Place an order for one item which will decrease the stock accordingly

Figure 2 shows the architecture of the CICS catalog manager application:

Figure 2: Architecture of the CICS catalog manager application

In this scenario we modify the place order operation. When this operation is invoked, the stock is decreased by the number of ordered items, and another program is also triggered: the dispatch manager program. The dispatch manager program dispatches the order to the supply chain. As figure 2 shows, the program can be configured to use either the dummy dispatch manager DFH0XSOD, or the dispatch manager DFH0XWOD which is an outbound Web Service call in CICS. We won’t use the DFH0XWOD program but we will replace that program with a new one: MOP0XAOD. This program will dispatch the order to the supply chain server (API provider) through a REST API using the z/OS Connect EE API requester capability.

Figure 3: Example scenario using the CICS catalog manager application

Note: we refer to the API provider as the remote API.

Figure 4 shows the new architecture of the CICS catalog manager application to call the REST API provider:

Figure 4: New CICS catalog manager architecture to call the REST API provider


The API provider is a supply chain application which is in charge of providing ordered items to the customer. This application is consumed through a REST API. The REST API is documented with a Swagger document.

Description of our example scenario:

  1. The web service program DFH0XWOD is replaced with the MOP0XAOD program.
  2. When an order is processed in the catalog manager application, the MOP0XAOD program is invoked with some information about the order: item reference, quantity, user and charge department.
  3. The MOP0XAOD program calls the communication stub: BAQCSTUB which is a program supplied by z/OS Connect EE, with the data needed to create the REST call to the API provider.
  4. The communication stub sends the data to the z/OS Connect EE server.
  5. The z/OS Connect EE server creates the HTTP request and sends it to the API Provider.
  6. The response follows the same flow, in the reverse order.

The implementation of the API requester capability in the CICS catalog manager application is done through 3 steps:

  1. Generate the artifacts from the remote API Swagger document
  2. Set up the z/OS Connect EE server to be able to receive calls from the communication stub and to send HTTP requests to the remote API
  3. Modify the COBOL code in the new MOP0XAOD program

3.1 Generate the artifacts

The z/OS Connect EE build toolkit is used for the generating the artifacts. The tool is a command line tool which takes the Swagger document provided by the API provider as input. The name of that Swagger document used in our example scenario is OrderDispatch.json. The following artifacts are generated:

  1. Copybooks to be used by the new dispatch manager program MOP0XAOD to call the communication stub program.
  2. API Requester Archive (ARA) file to be used by the z/OS Connect EE server to perform the data transformation (data structure/JSON) and to link to a connection endpoint.

The z/OS Connect EE build toolkit can run on any Java platform: z/OS, MacOS, Linux and Windows. In our example scenario we used the z/OS version. Example 1 shows the command to run the z/OS Connect EE build toolkit:

zconbt.zos -p=./orderDispatch/orderDispatch.properties -f=./orderDispatch/archives/Order-Dispatch-API_V1.0.0.ara

Example 1 Usage of the z/OS Connect EE build toolkit

Example 2 shows the orderDispatch.properties file that contains the configuration used to run the tool:

 ## Sample properties file for API requester ## Assume user runs command under z/OS Connect build tool installation path.

 ## mandatory properties. ##

 # Specify the location and name of a swagger document.
 apiDescriptionFile=OrderDispatch.json
 # Specify where the generated data structure should be stored.
 dataStructuresLocation=//'ZOSCON.ZCEE.APIR.ORDER'
 # Specify where the generated API client code should be stored.
 apiInfoFileLocation=//'ZOSCON.ZCEE.APIR.ORDER'
 # Specify the directory where the log generated from the Build Toolkit is stored.
 logFileDirectory=logs
 # Specify the language for the code generation.
 language=COBOL
 # Specify the name of the connection to identify the RESTful endpoint.
 connectionRef=orderDispatchAPI

 ## optional properties. ##

 # Specify a prefix for the generated data structures and API client code.
 requesterPrefix=OOD
 # Specify the CCSID that is used at run time to encode character data in the application data structure.
 # By default, runtimeCodePage is set=CP037.
 runtimeCodePage=1047

Example 2 Properties file for the z/OS Connect EE build toolkit

The name of the API requester created is the concatenation of the title and the version from the Swagger document. In our example the name is Order-Dispatch-API_1.0.0. Here is the beginning of the swagger file:

{ "swagger" : "2.0",
  "info" : {
    "description" : "Order Dispatch operations that allow to register a new order to be dispatched and list already dispatched orders",
    "version" : "1.0.0",
    "title" : "Order Dispatch API"
  },


Example 3 Beginning of the Swagger document provided by the API provider

To avoid naming convention issues, we created the ARA file when running the zconbt command with the same name displayed in the title field in the Swagger document. And for version control we add the version to the name for the ARA file. We end up with the name Order-Dispatch-API_V1.0.0.ara for the ARA file.
 

3.2 Setting up the z/OS Connect EE server

In order for z/OS connect EE server to be able to manage the call to the API provider we need to do 2 configurations:

  1. We add the ARA file generated by the z/OS Connect EE build toolkit
  2. We add the endpointConnection element in the server.xml

We send by FTP the ARA file to the apiRequesters directory of the z/OS Connect EE server. This directory is configured by the zosconnect_apiRequesters element in the server.xml.
z/OS Connect EE server incorporates the new ARA file and displays a message that indicates the successful deployment of the ARA file in the messages.log file:

BAQR1102I: z/OS Connect EE API requester package Order-Dispatch-API_1.0.0 installed successfully.

Example 4 Message in the messages.log of the z/OS Connect EE server which shows the deployment of the ARA file

In the server.xml we tell z/OS Connect EE server where the API provider is. This is done with the zosconnect_endpointConnection element:

<zosconnect_endpointConnection id="orderDispatchAPI"
       host="https://apigwDP1.pssc.mop.fr.ibm.com"
       port="80"
       domainBasePath="/mpl-icc/z-api-mpl/"
       connectionTimeout="2s"
       receiveTimeout="5s" />

Example 5 endpointConnection element added in the server.xml

The id of the zosconnect_endpointConnection is the one we set up in the properties file when using the z/OS Connect EE build toolkit: this is the value of the field connectionRef.

3.3 Modifying the COBOL code

The z/OS Connect EE build toolkit generates 3 copybooks that are used by our new program MOP0XAOD:

  1. OOD00I01 which contains information about the API to be called: name, path, HTTP verb, etc… This copybook is already prepopulated.
  2. OOD00Q01 which contains data the program needs to provide for the request to the communication stub.
  3. OOD00P01 which contains data the program will receive in the response from the communication stub.

To call the communication stub our new program will also need to add the BAQRINFO copybook provided by z/OS Connect EE. This copybook manages security, and also response code information sent back by the communication stub.

We need to incorporate these 4 copybooks to our new program MOP0XAOD and create some logic between the information received from the main catalog manager program DFH0XCMN and the information needed by z/OS Connect EE to do the call to the API provider.
The source of that program can be found in the following Github repository: zcee-apir-orderdispatch-sample.
The next step is to compile and to link the new source. Do not forget the RENT (re-entrant) option in the COBOL compilation of the program that calls the communication stub.

If it’s not already done, we need to enable the communication stub in the CICS region. Refers to the IBM knowledge center for detail information: Configuring CICS to access the z/OS Connect EE server

The CICS catalog manager application is configured to use the new dispatch program MOP0XAOD with the ECFG transaction. In this transaction, we set the use of the outbound dispatcher to YES and specify the order dispatch web service program with the new name MOP0XAOD.

Figure 5 3270 screen of the ECFG transaction

4. Testing the Scenario

When we place an order on the EGUI catalog manager transaction, the new COBOL program MOP0XAOD will call the z/OS Connect EE server through the communication stub with information about the order. The z/OS Connect EE server will create the HTTP request and send it.

Figure 6 shows a new order for 2 items 70 on 3270 screen.

Figure 6 CICS catalog manager 3270 screen to place on order

Figure 7 shows the new order in the supply chain Order Dispatcher application which is called through the REST API.

Figure 7 Supply chain Order Dispatcher application


For more information about error messages refer to the IBM knowledge center: z/OS Connect EE communication stub (CICS) messages

Example 6 shows the error in the CICS log if the z/OS Connect EE server is not available:

 0055EGUI 20180323154724 Error code: 0000000008
 0055EGUI 20180323154724 Error msg:BAQT0008E 2018/03/23 15:47:24 Socket error.
 0055EGUI 20180323154724
 0055EGUI 20180323154724
 0055EGUI 20180323154724
 0055EGUI 20180323154724
 0055EGUI 20180323154724
 0055EGUI 20180323154724
 0055EGUI 20180323154724
 0055EGUI 20180323154724 Error origin:STUB


Example 7 shows the error message in the messages.log file of the z/OS Connect EE server if the API provider is not available:

[3/23/18 13:12:42:501 GMT] 00005bae .ibm.ws.jaxrs.2.0.common:1.0.18.cl170320170927-1854(id=183)] W Interceptor for {http://10.3.20.82:9081}WebClient has thrown excep-tion, unwinding now
org.apache.cxf.interceptor.Fault: Could not send Message.

5. Summary

This example scenario shows how to call a remote API from a z/OS application using the z/OS Connect EE API requester capability. In this article we didn’t talk about security, for further information on this topic, see the article: ‘Use the OAuth support to call the OrderDispatch API’.

This article is one of a series of articles on z/OS Connect EE security written by the IBM Montpellier Client Center team, Aymeric Affouard, Eric Phan and Nigel Williams.

More information about using API Requester with z/OS Connect EE can be found in the IBM Knowledge Center.