How to deploy an API?

This topic explains about how to deploy an API

You can use this information to learn how to deploy REST APIs for COMMAREA based CICS Applications running on TXSeries regions.

Prerequisites

CICS Transaction Gateway Version 9.2:For download and documentation information of CICS Transaction Gateway, visit http://www-03.ibm.com/software/products/en/cics-ctg
node.js version 4.6.0: For download and documentation information of nodejs, visit https://developer.ibm.com/node/sdk/#v4
IBM API Connect Version 5.0.4: For installation and usage information of IBM API Connect, visit https://developer.ibm.com/apiconnect/getting-started

Machine Setup

To enable REST API support for TXSeries applications, Install CICS TG where you have TXSeries 9.1 installed.
Install node.js, CICS TG and IBM API Connect on x86 Linux machine which you want to use as API endpoint.
Copy loopback-connector-txseries.tgz file from <TXSeries Install Dir>/etc/loopback-connector/loopback-connector-txseries.tgz to machine where you have IBM API Connect. loopback-connector-txseries is a TXSeries connector for the LoopBack framework.
For more information about LoopBack connector visit https://docs.strongloop.com/display/public/LB/Getting+started+with+LoopBack

Note: Internet access may be required during installation and configuration of node.js, IBM API Connect and loopback-connector-txseries.

CICS Region side configuration

Configure an IPIC based listener
- Add IPIC Service entry in /etc/service file.
- Configure CICS for IPIC over TCP/IP. See Configuring CICS for IPIC over TCP/IP support for more information about how to configure CICS for IPIC over TCP/IP.
  cicsadd -c ld -r <REGION NAME> LD01 Protocol=IPIC TCPService=<IPIC Service>
- Configure the CICS Transaction Gateway to communicate to above region. Use ctgcfg tool to configure a IPIC Server entry for the above configured region.
  See Figure 2 for reference.
  
  Figure 2. Configure the CICS Transaction Gateway
- Start CTG Gateway daemon using the command ctgstart.
Configure TXSeries Application for REST API.
Identify and group a set of CICS applications which operates on a same COMMAREA and use cicsrestconfig tool to enable these set of applications for REST.
```
Usage: cicsrestconfig { help | -r REGION_NAME -c RESOURCE_NAME -l LANG -a LS-PATH [-s STRUCTURE_NAME] -p PROGRAMS }
```
where
- REGION_NAME - Name of the region where RESTifying TXSeries Applications are installed.
- RESOURCE_NAME - Name of the COMMAREA on which TXSeries Applications operates.
- LANG – Programming Language on which your applications are written ( C/COBOL ; For Beta only C and COBOL applications is supported ).
- LS-PATH - Absolute Path to Copybook/Header file.
- STRUCTURE_NAME – If the language is C, then provide the Structure name which is used as COMMAREA in your applications.
- PROGRAMS - ',' separated list of Program Definition (PD) Name operates on the COMMAREA.
Consider DigitalLibrary as an example for better understanding, we have four set of programs CRTEBOOK,GETIBOOK,UPDTBOOK and DELTBOOK installed in region BOOREGN, which all operates on a BOOKREC CopyBook located at /var/cics_regions/BOOKREC/bin/BOOKREC.cpy. See Figure 3 for reference.

Figure 3. RESTify a COBOL based TXSeries Application
Use the cicsrestconfig tool as bellow.
```
cicsrestconfig -r BOOKREGN
            \-s BOOKREC \-l COBOL \-a
            /var/cics_region/BOOKREGN/bin/BOOKREC.cpy \-p
            CRETEBOOK,GETIBOOK,UPDTBOOK,DELTBOOK
```
Now lets see how to RESTify a C based TXSeries Application, which gives us the practical usage of cicsrestconfig tool

See Figure 4 for reference.

Figure 4. RESTify a C based TXSeries Application
Use the cicsrestconfig tool as bellow
```
cicsrestconfig -r BOOKREGN
            \-s BOOKREC \-l C \-a
            /var/cics_region/BOOKREGN/bin/bookrec.h \-s BOOKREC \-p
            CRETEBOOK,GETIBOOK,UPDTBOOK,DELTBOOK
```

Create and deploy IBM API Connect Application

In machine where you have installed IBM API Connect and loopback-connector-txseries perform the following step

Set the NODE_PATH to global node_modules directory
Create an empty-server IBM API Connect application by using the command apic loopback
Switch to IBM API Connect application directory
Install loopback-connector-txseries as a privileged user (root or sudoer) using the following command npm install <Copied Directory>/loopback-connector-txseries.tgz -unsafe-perm.
Use apic-txseries command to configure TXSeries DataSource and to discover CICS Applications which are enabled for REST as explained above
Note: TXSeries DataSource: Its a LoopBack DataSource provides an entry point to your TXSeries region via CTG, See Figure 5 for reference.

Figure 5. Create and deploy IBM API Connect Application
Configure TXSeries DataSource.
Select the Install new DataSource option, then the tool will ask for set of configuration questions like
- Enter data source name : Enter the name of the DataSource for your identification
- Enter the CICS Transaction Gateway(CTG) IP Address/Domain Name: Enter the IP Address of CTG which is configured to communicate to your TXSeries region.
- Enter the CICS Transaction Gateway (CTG) Port Number: Enter the CTG listener port number
- Enter the IPIC Server name defined at CICS Transaction Gateway: Enter the name of IPIC Server with which you are configured your region.
- Enter CICS Username: Enter the CICS User ID. With this you can restrict access to TXSeries applications only to authenticated CICS User. By default CICSUSER is default CICS User
- Enter CICS Password: Enter the CICS Password for above CICS User
- Discover TXSeries Applications from all the configured TXSeries DataSources
See Figure 6 for reference.

Figure 6. Configure TXSeries DataSource
Discover TXSeries Datasource
- Run apic-txseries and select second option, it will list all the TXSeries DataSources configured in the IBM API Connect Application. You can select the DataSources which all you want to discover.
  See Figure 7.
  Figure 7. Run slc-txseries
- Once the DataSource selected press enter. Tool will discover all TXSereies application that are RESTified for all of the selected TXSeries DataSources. See Figure 8 for reference.
  Figure 8. Discover TXSeries Services
  
  The operation will list all discovered Resources. In our DigitalLibrary example we had configured BOOKREC as the Resource, and which is now got discovered from TXSeries DataSource.
- Once the Resource are discovered, you can select them to compose RESTful API. See Figure 9 for reference.
  Figure 9. REST
  
  Before RESTifying them you can now compose them for better usability. For each of the selected resource the tool will asks for compose confirmation. Say yes if you want to compose and configure selected models and say no if you want to use it as it is
- For the DigitalLibrary example, we are proceeding to compose and configure the BOOKREC resource. Now you can disable the properties that you dont want to expose with REST API. See Figure 10 for reference.
  Figure 10. Enable/disable properties
- Once the properties are configured, the tool will ask for PathParameter. Select the property that you want to use as a PathParamter. Once the PathParamter set you can do querry based on PathParamter directly with a condition that your TXSeries also performs the querry based on the same PathParamter property. See Figure 11 for reference.
  Figure 11. PathParameter
  
  In example bookname is selected as PathParamter so that REST API can do search based on bookname directly.
- Now map HTTP operations to your TXSeries application which operates on the selected Resource. The tool will ask for mapping TXSeries application to respective HTTP operations. For the DigitalLibrary CRTEBOOK TXSeries Application is used to create BOOK resource, so this particular application is mapped to POST Operation of HTTP. See Figure 12 for reference.
  Figure 12. Mapping
  
  Similarly map other TXSeries Applications to respective HTTP operations based on their functionality. See Figure 13 for reference.
  Figure 13. HTTP Operations
  
  In example TXSeries application CRTEBOOK maped to HTTP operation POST, GETIBOOK is mapped to HTTP GET operation , UPDTBOOK is mapped to HTTP PUT operation and finally UPDTDELT is mapped to HTTP DELETE.
- Now you are done with creating model for BOOKRECORD in your DigitalLibrary.
- Start IBM API Connect application by apic start command. You can start API Designer using apic edit command to manage and explore the REST APIs. DigitalLibrary API explorer is as shown in Figure 14.
  
  Figure 14. DigitalLibrary API Explorer