ibm-itx-rs REST API

The ibm-itx-rs container exposes a Swagger UI web page which documents the supported APIs. This web page can be displayed by pointing your web browser to:

http://CONTAINER_HOSTNAME:8080/itx-rs/api-docs?url=/itx-rs/openapi.json

In addition to the OpenAPI 3.0 version, the REST APIs are also represented in the Swagger 2.0 version. You can explore the API in this format in the web browser by pointing it to:

http://CONTAINER_HOSTNAME:8080/itx-rs/api-docs?url=/itx-rs/swagger.json

Where CONTAINER_HOSTNAME is the IP address or hostname assigned to the running container. If the container is running under cluster environment like Red Hat OpenShift, use ingress or route name of the ITX Runtime Server.

The following REST APIs are supported:

Version

GET http://CONTAINER_HOSTNAME:8080/itx-rs/v1/version

Where CONTAINER_HOSTNAME is the IP address or hostname assigned to the running container.

The return value is JSON in the format:

{
"version": "10.1.2.1",
"name": "IBM Sterling Transformation Extender Runtime Server",
"revision": "0",
"date": "20250328"
}

This API call can be used as a heartbeat mechanism for ensuring the container is up and running.

Configuration

GET http://CONTAINER_HOSTNAME:8080/itx-rs/v1/configuration

Where CONTAINER_HOSTNAME is the IP address or hostname assigned to the running container.

The return value is JSON in the format:

{
"run_mode":"unfenced",
"redis_host":"",
"redis_port":6379,
"redis_timeout_seconds":2,
"redis_password":"",
"redis_stem":"itx-rs",
"redis_catalog_cache_enabled":false,
"map_file_extension":"lnx",
"map_unload_time_minutes":10,
"map_max_threads":50,
"log_include_host_in_log_names":false,
"log_access_log_level":"all",
"log_access_log_days":-1,
"log_exec_log_file_count":5,
"log_exec_log_file_size_kib":100,
"log_exec_log_level":"all",
"log_exec_log_std_err":true,
"log_server_log_level":"info",
"log_server_log_days":-1,
"log_service_log_level":"info",
"log_service_log_days":-1,
"log_service_log_std_err":true,
"log_jni_log_level":"none",
"log_cmgr_log_level":"none",
"ssl_enabled":false,
"ssl_client_auth":false,
"resource_registry_config_file":""
}

The following list describes each setting and indicates the environment variable that can be used to control the value of that setting when creating the container instance:

Setting	Description
ITX_RS_RUN_MODE	Runtime mode of the server, fenced or unfenced, default is unfenced
ITX_RS_MAP_FILE_EXTENSION	File extension of compiled maps, default is lnx
ITX_RS_MAP_UNLOAD_TIME_MINUTES	Time in minutes to keep accessed map in cache, default is 10
ITX_RS_MAP_MAX_THREADS	The upper limit for the number of mapping threads, default is 50
ITX_RS_MAP_SYNC_TIMEOUT_SECONDS	Synchronous map execution timeout in seconds, default is 300
ITX_RS_LOG_INCLUDE_HOST_IN_LOG_NAMES	Include current host name in the generated log file names
ITX_RS_LOG_ACCESS_LOG_LEVEL	Severity level threshold for access log messages
ITX_RS_LOG_ACCESS_LOG_DAYS	Number of days to keep access logs, or -1 for unlimited time
ITX_RS_LOG_SERVER_LOG_LEVEL	Severity level threshold for server log messages
ITX_RS_LOG_SERVER_LOG_DAYS	Number of days to keep access logs, or -1 for unlimited time
ITX_RS_LOG_SERVICE_LOG_LEVEL	Severity level threshold for service log messages
ITX_RS_LOG_SERVICE_LOG_DAYS	Number of days to keep service logs, or -1 for unlimited time
ITX_RS_LOG_SERVICE_LOG_STD_ERR	Write service log messages to the standard error as well
ITX_RS_LOG_EXEC_LOG_FILE_COUNT	Number of files to keep in the circular log, default is 5
ITX_RS_LOG_EXEC_LOG_FILE_SIZE_KIB	Size of log in kilobytes before proceeding to the next log file, default is 100
ITX_RS_LOG_EXEC_LOG_LEVEL	Log severity level (none, failures or all), default is all
ITX_RS_LOG_EXEC_LOG_STD_ERR	Write execution log messages to the standard error as well
ITX_RS_LOG_JNI_LOG_LEVEL	Severity level threshold for JNI (Java Native Interface) log messages
ITX_RS_LOG_CMGR_LOG_LEVEL	Severity level threshold for connection manager log messages
ITX_RS_REDIS_HOST	Host name of the Redis server
ITX_RS_REDIS_PORT	Port number of the Redis server, default is 6379
ITX_RS_REDIS_TIMEOUT_SECONDS	Timeout, in seconds, for establishing Redis connections
ITX_RS_REDIS_STEM	Prefix to use for all Redis key names produced and consumed by server
ITX_RS_REDIS_CATALOG_CACHE_ENABLED	Enable Redis caching of map catalog entries
ITX_RS_SSL_ENABLED	Use HTTPS for invoking REST endpoints in the pods
ITX_RS_SSL_CLIENT_AUTH	Enable certificate authentication of the clients when calling endpoints
ITX_RS_RESOURCE_REGISTRY_CONFIG_FILE	Resource registry configuration file, default is null (no file is used)

Direct Map Invocation

PUT http://CONTAINER_HOSTNAME:8080/itx-rs/v1/maps/direct/PATH

POST http://CONTAINER_HOSTNAME:8080/itx-rs/v1/maps/direct/PATH

Where CONTAINER_HOSTNAME is the IP address or hostname or ingress/route name assigned to the running container and PATH is the path to the compiled map file, relative to the location corresponding to the maps mount point, and with the .lnx file extension omitted.

POST method runs the map asynchronously. Redis is required to be setup to run maps in this mode of execution to find the status of the map execution, fetching outputs, map trace and map audit from the Runtime Server. Environment variables for running map in fenced mode, Redis server host and port options listed in previous page must be passed when launching the Runtime Server container. Fenced mode ensures that an ITX failure does not affect the web server. Fenced mode is required to run a map asynchronously. In unfenced run mode, the servlet runs within the web server.

The following query parameters are supported:

input
The input query parameter is used for overriding source data settings in input cards. Multiple input overrides can be specified by a comma-separated list, or by specifying multiple input parameters. Each value is either an input card number (if the card data is being provided in the request body), or an adapter specification in the form:
```
card-num;adapter-alias;adapter-command
```
For example: to specify that the data for card 2 should be from a file:
```
input=2;FILE;mydata.txt
```
output
The output query parameter is used to specify which output cards should be returned. Multiple output overrides can be specified by a comma-separated list, or by specifying multiple output parameters. Each value is either an output card number (if the card data should be returned in the response body), or an adapter specification in the form:
```
card-num;adapter-alias;adapter-command
```
For example: to specify that the data for card 2 should be written to a file:
```
output=2;FILE;results.txt
```
return
The return query parameter is used to specify the type of information to return about the executed map. Permitted values are status, statusonerror, audit, auditonerror, trace, and traceonerror. Multiple values can be specified, as a comma-separated list in a single return query parameter, or by using multiple return query parameters.