ibm-itx-rs REST API

Edit online

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/tx-rest/api-docs?url=/tx-rest/docs

Where CONTAINER_HOSTNAME is the IP address or hostname assigned to the running container. If the container is running under a cluster environment like Red Hat OpenShift, use ingress or route name of the ITX Runtime Server. Replace the default text v2/docs or v1/itx/docs in the search box with openapi.json and select the Explore button in the Swagger UI web page.

By default, all the deployed map and flow endpoints for V2 REST API are displayed in the Swagger UI web page. If the rest.defaultSwagger property is set to v1, then all cataloged map endpoints for V1 REST API are displayed in the Swagger UI page.

The following REST APIs are supported:

Version
GET http://CONTAINER_HOSTNAME:8080/tx-rest/v1/itx/version

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

The return value is JSON in the format:

{
"version": "11.0.1.1",
"name": "IBM Sterling Transformation Extender for Red Hat OpenShift",
“up_time”: "1 days, 4 hours, 18 minutes, 44 seconds",
"date": "20250425",
"revision": "0"
}

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

Configuration
GET http://CONTAINER_HOSTNAME:8080/tx-rest/v1/itx/configuration

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

The return value is JSON in the format:

{
    "map_dirs": [
        "/data/maps"
    ],
    "work_dir": "/data/tmp",
    "catalog_dir": "/data/catalog",
    "redis_host": "localhost",
    "redis_key_stem": "tx-rest",
    "is_fenced": true,
    "unload_time": 60000,
    "max_map_threads": 10,
    "exec_log_dir": "/logs"
}
Direct Map Invocation
PUT http://CONTAINER_HOSTNAME:8080/tx-rest/v1/itx/maps/direct/PATH
POST http://CONTAINER_HOSTNAME:8080/tx-rest/v1/itx/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 .mmc 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.