Customizing and running the REST API

This topic describes how to configure and run your REST API service.

About this task

The following members need to be customized:
Table 1.
JCLLLIB/PARMLIB members Description
HSISAPIE (PARMLIB) Environment variable.
HSISAPIP (JCLLIB) Job to invoke the REST API.
Table 2.
UNIX member Description
odbc.ini This file is referenced by parameter DSNAOINI in PARMLIB member HSISAPIE. File 'odbc.ini' is provided under the API installation folder. In this file only parameter MVSDEFAULTSSID needs to be updated with the Db2 subsystem name or a Group Attach name (for DSG).

Procedure

  1. Customize PARMLIB member HSISAPIE.
    Parameters Description
    UNX_API_PATH Path to the API installation folder ( e.g. /api_install/dist).
    PROD_PORT Port where API will listen for incoming requests (e.g. 8000).
    PROD_WORKERS Number of concurrent request handlers (recommended value of 3).
    TLS_CERT_FULLNAME Full path to the TLS certificate (e.g. /u/user/domain.crt).
    TLS_KEY_FULLNAME Full path to the TLS key (e.g. /u/user/domain.key).
    IBM_DB_HOME The hlq for Db2 libraries used for accessing SDSNC.H and SDSNMACS. If SDSNMACS uses a different prefix, then define Db2_MACS as an environment variable. If SDSNHC.H uses a different prefix, then define Db2_INC as an environment variable.
    DSNAOINI The odbc.ini file containing ODBC/CLI parameters. A sample is provided under the API installation folder and must be customized according to your site requirements.

    Note: File must be tagged as either binary or IBM-1047 with text tag set to 'off'.(T=off when running chtag -podbc.ini command).
  2. Customize JCLLIB member HSISAPIP. Following is an example: 
    //HSISAPIP JOB, 'REST API job',REGION=0M,TIME=NOLIMIT,
// CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1),NOTIFY=&SYSUID
//* STEP1: Launch the REST API job
//STEPEXEC EXEC PGM=BPXBATCH,REGION=0M,TIME=NOLIMIT
//STEPLIB DD DISP=SHR,DSN=db2.SDSNEXIT            
//        DD DISP=SHR,DSN=db2.SDSNLOAD            
//        DD DISP=SHR,DSN=db2.SDSNLOD2            
//*
//STDIN    DD PATH='/dev/null',PATHOPTS=(ORDONLY)
//STDOUT   DD SYSOUT=*
//STDERR   DD SYSOUT=*
//STDENV   DD DISP=SHR,DSN=&HSIINST.PARMLIB(HSISAPIE)
//STDPARM  DD *
SH cd $UNX_API_PATH; ./run.sh --prod
/*

    Replace the hlq for STEPLIB library db2.SDSNLOD2.

    Replace &HSIINST with the value specified in the customization job, HSISCUST.

  3. In odbc.ini, parameter MVSDEFAULTSSID needs to be updated with the Db2 subsystem name or Group Attach name (for DSG).
    Note: File must be tagged as either binary or IBM-1047 with text tag set to 'off'. (T=off when running chtag -podbc.ini command).
  4. Update the user .profile file. To run Python you need to set the Python installation path.
    Following is an example: 
    export LIBPATH=/hcl/tcypz3b/usr/lpp/IBM/cyp/v3r11/pyz/lib:$LIBPATH
export PATH=/hcl/tcypz3b/usr/lpp/IBM/cyp/v3r11/pyz/bin:$PATH
  5. Optionally, a subset of API configurations can be provided directly on UNIX, with the configuration script config.sh contained in the root project directory. This configuration option can be used to further configure UNIX environment variables, such as the Python installation PATH, or LIBPATH variables and C Compiler related options.

Running the REST API

This topic describes how to run IZSAM REST API. The HSISAPIP job in the JCLLIB library is used to start up the REST API service.

About this task

Procedure

  1. Submit HSISAPIP.
  2. To query the REST API, you can use tools such as CURL, or other REST API client tools.