Link Runtime REST API

The Link Runtime REST API is used to run the Link Maps and Flows using REST API calls. These instructions describe how to configure the Link REST API as a native application or docker application.

Installing the Link REST API using Link installation scripts

Prerequisites:

  • Download the Link installation on your Linux or Windows computer.
  • On Linux computer, untar the Link installation tar.gz files.

Configuring the REST API

On Windows:

Start the InstallShield Link installation as administrator user, then follow the installation wizard instructions to configure the REST API, under custom option select REST API option to install REST API, during the installation select location where REST API will keep its data and configuration files.

On Linux:

The config.yaml configuration file is in the directory where the installation files are untarred. Comments in the configuration file explain each property.

Set the following properties in the config.yaml file (under rest.persistance section), the directories you specify in the configuration file must be existing directories with the ownership of the current Linux user that installs the link application:
  • maps - One or more directories that contain the compiled map files.
  • files - Various runtime files. Shared directory between Server and REST.
  • catalog - The directory where the map catalog file is to be created.
  • work - The directory for temporary files used during map execution.
  • log - The directory where map execution logs are written.
  • Config - The Configuration files.
Run the following command to configure the type of Link installation, native or docker: 
./Link configure -t docker
./Link configure -t native
Run the following command to install the Link for Linux:
./Link install --runtime

Enabling Runtime REST API Authentication

Note: The Windows installation have configuration config.yaml file located in <install_dir>/config/config.yaml location.
Note: For Windows, this is an optional task after installation, and for Linux, this is an optional task before and after installation.

The Rest API calls authentication can be configured using the rest.inbound.authentication settings from the config.yaml file. By default, authentication is disabled. To enable the Rest API authentication, set authentication.enabled to true.

Default authentication.server is https://localhost:8443, to use the Link servers running remotely, change the value to point to the authentication.server URL.

For example, authentication.server=https://<ipaddress>:<port>

  • Where<ipaddress> is the IP address of the authentication server installation (or its host name).
  • <port> is the port on which the authentication server listens for requests (typically the port number is 8443).

To enable the Link Runtime REST API authentication, modify the .authentication settings:

  1. Set the authentication.enabled to true to enable the authentication.
  2. Enter the correct IP port of the Link server installation. For example,
    https://<LNK server IP>:8443
    Note: Make sure that TCP address <LNK server IP>:8443 is not blocked by the firewall or it is visible within the Rest container, if container installation is done.
  3. If Link is not Installed, install the Runtime REST API, docker or native install as mentioned in previous section. If Link is already installed restart the Link application:

    On Windows, cd to <installation_dir>/DesignServer and restart Link by running stop.bat/start.bat commands.

    On Linux, run “./Link stop”, “./Link start --runtime”

  4. Open the SWAGGER URLs in the browser to select browse and/or runt Link REST api calls:
    • https://< LNK runtime REST API IP >:< LNK runtime REST API PORT >/hip-rest/api-docs?url=v2/docs
    • https://<LNK runtime REST API IP>:<LNK runtime REST API PORT>/hip-rest/api-docs?url=openapi.json
    Note: Where the Link Runtime REST API IP is the HOST IP of the machine where REST API is installed. The Link Runtime REST API PORT is the API port, for example localhost:9443.
  5. Use the new Authentication option to invoke the Link REST runtime calls. For example, use the Link REST runtime session API to create bearer token or basic authentication: https://<LNK runtime REST API IP>:<LNK runtime REST API PORT>/hip-rest/api-docs?url=openapi.json#/Sessions/createOwnSession.
  6. Use the token or basic authentication to invoke other Link rest calls to browse and access the Link Runtime REST API.
Note: The Link Runtime REST API Authentication can be used only in combination with HTTPS scheme.

Swagger documentation

To view the Swagger documentation for the Link REST APIs, enter the following URL in a browser: 

http://< HIP Runtime REST API server>:8080/hip-rest/api-docs?url=/hip-rest/openapi.json

You can invoke the APIs directly from the Swagger interface by clicking Try it out under each API definition.

See the Link API documentation in the online documentation and the tutorial installed in install_dir\examples\restapi for details about using the Link Runtime REST API.

REST API installation using external Application servers

To deploy the REST API on an external server, you can follow the given instructions for both Tomcat and JBoss/Wildfly setups:

Tomcat Setup:
  1. Copy the hip-rest.war file to the Tomcat deployment directory (tomcat/webapps).
  2. Install the binary distribution of Apache Tomcat version 9.0.46 or higher.
  3. Set Environment Variables (Linux):
    • Create a setenv.sh file in $CATALINA_HOME/bin/ if it does not exist. Add the following lines in setenv.sh:
      export DTXHOME=/opt/hcl/hip
export DTX_DATA_DIR=/opt/hcl/hip
export JAVA_HOME=$DTXHOME/java
export CATALINA_OPTS="$CATALINA_OPTS -Djava.library.path=$DTXHOME/libs -Djava.util.logging.SimpleFormatter.format='%tFT%<tT.%<tL %4$4.4s %3$s %5$s %n'"
export PATH="$DTXHOME/bin:$JAVA_HOME/bin:$PATH"
export LD_LIBRARY_PATH="$DTXHOME/libs:$LD_LIBRARY_PATH"
export TX_REPOSITORY_DIR=/tmp/tx-repos
export TX_FILE_DIR=/data/files
export TX_QUEUE_DIR=/tmp/tx-queue
  4. Set Environment Variables (Windows):
    • Create a setenv.bat file in %CATALINA_HOME%\bin\ if it does not exist. Add the following lines in setenv.bat:
      set DTXHOME=C:\HCL\Link_10.9.9
set DTX_DATA_DIR=C:\HCL\Link_10.9.9
set JAVA_HOME=%DTXHOME%\java
set CATALINA_OPTS=%CATALINA_OPTS% -Djava.library.path=%DTXHOME% -Djava.util.logging.SimpleFormatter.format='%tFT%<tT.%<tL %4$4.4s %3$s %5$s %n'
set PATH=%DTXHOME%;%JAVA_HOME%\bin;%PATH%
set TX_REPOSITORY_DIR=C:\tmp\tx-repos
set TX_FILE_DIR=C:\data\files
set TX_QUEUE_DIR=C:\tmp\tx-queue
  5. Modify the DTXHOME value as necessary to match your Link installation directory.
  6. Set DTX_DATA_DIR to represent the directory for config/config.yamland the log folder.
JBoss/Wildfly setup:
  1. Install Link for Windows.
  2. Set Environment Variables (Windows):
    • Change the DTXHOME value to match your Link installation directory. Set DTX_DATA_DIR to represent the directory for config/config.yaml and the log folder. Set CLASSPATH:
      DTXHOME = C:\HCL\Link_10.9.9
DTX_DATA_DIR=C:\HCL\Link_10.9.9
CLASSPATH=C:\HCL\Link_10.9.9/libs/dtxpi.jar:$CLASSPATH
DTX_HOME_DIR=C:\HCL\Link_10.9.9
DTX_TMP_DIR=/opt/IBM/itx10/tmp
HIP_WEBINF_PATH=<server-path>/standalone/deployment/hip-rest/WEB-INF
  3. Update the config.yaml file in the REST section to enable Runtime REST API Authentication.
  4. Workarounds for JBoss: The following workarounds are suggested to enable deployment on JBoss along with latest hip-rest.war file:
    • Remove jax-rs entries from standalone.xml as following:
      <!-- <extension module="org.jboss.as.jaxrs"/> -->
<!-- <subsystem xmlns="urn:jboss:domain:jaxrs:2.0"/> -->
    • Extract hip-rest.war to hip-rest under /standalone/deployments/ directory to enable exploded mode deployment
    • Set the environment variable HIP_WEBINF_PATH with the complete deployment directory path, for example:
      Variable name = HIP_WEBINF_PATH
variable value = <server-path>\JBOSS\standalone\deployments\tx-rest\WEB-INF