Installing the REST API

This topic describes the steps to install REST API.

There is a small configurator that automatically generates both your odbc.ini and api.config.toml.It prompts for:

The Db2® DSN
The API listening port
The desired log verbosity: suggested is info.
Output destinations for each file: we suggest leaving it with the default values.
Ibm_db_home: HLQ of the Db2® libraries.

Once you confirm, the tool writes a properly tagged ODBC/CLI file and a valid TOML configuration. This ensures your API server can be started immediately.


Name	Description	Default Value
Port	Port where the server will listen	8899
Database type	Type of database to use	Db2®
DSN	DSN of the Db2® database	QXPOMU2DEC2
Log	Log level (DEBUG, INFO, WARN, ERROR, OFF)	INFO
ibm_db_home	HLQ of Db2® libraries.	Db2.VC10

The configurator will also generate the JCLs needed to run the API almost already configured.There is also inside the PAX a file called CONFIGURE.txt which describes the steps needed to run the configurator. You can find the same instructions in the following section.

Step by Step Configuration

Extract the pax file with pax -rvf "//'<paxfile>'" and position yourself into the created dist directory
Run ./bin/configurator and follow the prompts. This will generate four files:
- odbc.ini
- api.config.toml
- hsisapie.jcl
- hsisapip.jcl
Take the generated jcls and copy them into a dataset of your choice. If you plan to copy the JCLs using option 3.17, you need to first convert them into the correct codepage for ISPF; This can be done by running the following commands while positioned inside the dist folder:
- iconv -f ISO8859-1 -t IBM-1047 hsisapip.jcl > hsisapip.converted.jcl
- iconv -f ISO8859-1 -t IBM-1047 hsisapie.jcl > hsisapie.converted.jcl
  Note:
  You can copy the converted JCLs via option 3.17.
Edit HSISAPIP such that the STDENV DD card points to the member where you copied HSISAPIE.
Submit HSISAPIP to start the API.

Expected Result

In the HSISAPIP generated JCL, you should obtain something similar to the following.

//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; ./bin/fzvsam-api/*

The HSISAPIE JCL should contain the following values:


PARAMETERS	DESCRIPTION
UNX_API_PATH	Path to the API installation folder ( e.g. /api_install/dist).
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 contains ODBC/CLI parameters.
UNX_CONFIG_PATH	Path to the `toml` configuration file.
USE_PASSPHRASE	Whether to enable the use of case sensitive passphrases. See Authorization for more details.

In the logs you should see something similar to the following:

2025-05-16T05:17:00-04:00-[INFO]: analyzer[analyzer/internal/api.NewApiServices] IBM Z Software Asset Management 9.1 REST API - log file 
2025-05-16T05:17:00-04:00-[INFO]: analyzer[analyzer/internal/api.NewApiServices] GET Registered route:  /end_of_service/count                        
2025-05-16T05:17:00-04:00-[INFO]: analyzer[analyzer/internal/api.NewApiServices] GET Registered route:  /end_of_service/report                       
2025-05-16T05:17:00-04:00-[INFO]: analyzer[analyzer/internal/api.NewApiServices] GET Registered route:  /product_inventory/count                     
2025-05-16T05:17:00-04:00-[INFO]: analyzer[analyzer/internal/api.NewApiServices] GET Registered route:  /product_inventory/report                    
2025-05-16T05:17:00-04:00-[INFO]: analyzer[analyzer/internal/api.NewApiServices] GET Registered route:  /product_use_by_machine/count                
2025-05-16T05:17:00-04:00-[INFO]: analyzer[analyzer/internal/api.NewApiServices] GET Registered route:  /product_use_by_machine/report               
2025-05-16T05:17:00-04:00-[INFO]: analyzer[analyzer/internal/api.NewApiServices] GET Registered route:  /product_use_by_month/count                  
2025-05-16T05:17:00-04:00-[INFO]: analyzer[analyzer/internal/api.NewApiServices] GET Registered route:  /product_use_by_month/report                 
2025-05-16T05:17:00-04:00-[INFO]: analyzer[analyzer/internal/api.NewApiServices] GET Registered route:  /repositories                                
2025-05-16T05:17:00-04:00-[INFO]: analyzer[analyzer/internal/api.NewApiServices] POST Registered route:  /any_query                                  
2025-05-16T05:17:00-04:00-[INFO]: analyzer[analyzer/internal/api.NewApiServices] Using DB2 with local connection                                     
2025-05-16T05:17:00-04:00-[INFO]: analyzer[analyzer/internal/api.NewApiServices] DB2 DSN: QXPOMU2DEC2                                                
2025-05-16T05:17:00-04:00-[INFO]: analyzer[analyzer/internal/api.NewApiServices] Hostname: PTHOMU2                                                   
2025-05-16T05:17:00-04:00-[INFO]: analyzer[analyzer/internal/api.NewApiServices] API running on port: 8111

Errors and Workarounds

The logs contain just an error of a failed connection to Db2®: This is probably a result of a misconfigured odbc.ini file. This file is very sensitive to character tagging. Try modifying the character set with the chtag command. If you are still facing problems try creating a new odbc.ini file with the same content.

It is important to not put any space at the beginning of the JCL files.

The logs contain random gibberish: This is probably due to the fact that in your .profile you are running a bash shell that is performing character conversion. The api will save logs in ebcdic format. Remove bash from the .profile. Alternatively you can modify the STDPARM DD card of the HSISAPIP jcl by changing it from:

SH cd $UNX_API_PATH; ./bin/fzvsam-api -> PGM /full/path/to/bin/fzvsam-api

This will prevent the JOB from sourcing the .profile before execution.