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
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.
The config.yaml configuration file is in the directory where the installation files are untarred. Comments in the configuration file explain each property.
- 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.
./Link configure -t docker
./Link configure -t native
./Link install --runtime
Enabling Runtime REST API Authentication
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:
- Set the
authentication.enabled
to true to enable the authentication. - 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. - 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”
- 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. - 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
. - Use the token or basic authentication to invoke other Link rest calls to browse and access the Link Runtime REST API.
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:
- Copy the hip-rest.war file to the Tomcat deployment directory (tomcat/webapps).
- Install the binary distribution of Apache Tomcat version 9.0.46 or higher.
- 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
- Create a setenv.sh file in
$CATALINA_HOME/bin/ if it does not exist.
Add the following lines in
setenv.sh:
- 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
- Create a setenv.bat file in
%CATALINA_HOME%\bin\ if it does not exist.
Add the following lines in
setenv.bat:
- Modify the DTXHOME value as necessary to match your Link installation directory.
- Set DTX_DATA_DIR to represent the directory for config/config.yamland the log folder.
- Install Link for Windows.
- 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
- 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:
- Update the config.yaml file in the REST section to enable Runtime REST API Authentication.
- 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
- Remove jax-rs entries from standalone.xml as
following: