Link Runtime REST API

Installing the Link REST API in a web server

Prerequisites:

• A web server that supports Servlet 3.0 containers, such as Tomcat, Glassfish, or Jetty.

Configuring the tx-rest.properties configuration file

The tx-rest.properties configuration file is installed in the installation directory (install_dir). Comments in the file explain each property.

At a minimum, set the following properties in the tx-rest.properties file. The directories you specify in the configuration file must be existing directories:

• map.dirs – One or more directories that contain the compiled map files.
• catalog.dir – The directory where the map catalog file is to be created.
• work.dir – The directory for temporary files used during map execution.
• redis.host – The host (and port) of the Redis server. By default, this is set to localhost.
• exec.log.dir – The directory where map execution logs are written.

Enabling Runtime REST API Authentication

If the authentication.enabled is set to true, the Rest API calls will be authenticated using the specified authentication.server. Default is false. To enable the Rest API authentication, specify 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.server 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. Install the Runtime REST API, docker or tomcat install.
4. Use the new Authentication option. For example, the LNK-REST runtime session API to create tokens
5. Use the token or basic authentication to invoke other Link rest calls to browse and access the Link Runtime REST API.
6. Open the SWAGGER URLs in the browser:
   • https://<LNK runtime REST API IP>:<LNK runtime REST API PORT>/hip-rest/api-docs?url=openapi.json
   • https://< LNK runtime REST API IP >:< LNK runtime REST API PORT >/hip-rest/api-docs?url=v2/docs

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.

Setting up the web server environment

You must set environment variables to enable the API to find the Link JAR and library files.

If you are using Inst, you can choose either of the following methods to set up the environment variables:

• The session that starts Tomcat can invoke the $DTX_HOME_DIR/setup script (or %DTXHOME%/DTXCommon.bat, on Windows systems) to set up the Link environment variables.

export DTX_HOME_DIR=" <install-dir>"
export CATALINA_OPTS="$CATALINA_OPTS -Djava.library.path=$DTX_HOME_DIR/libs"
export LD_LIBRARY_PATH="$DTX_HOME_DIR/libs:$DTX_HOME_DIR/java/bin:$DTX_HOME_DIR/java/lib/server:$DTX_HOME_DIR/java/lib:$DTX_HOME_DIR/unixODBC/linux/lib:$LD_LIBRARY_PATH"
export ODBCINST="$DTX_HOME_DIR/unixODBC/etc/odbcinst.ini"
export ODBCINI="$DTX_HOME_DIR/unixODBC/etc/odbc.ini"

Deploying the WAR file

The hip-rest.war file implements the REST API for Link. It's installed in the $DTX_HOME_DIR/restapi directory. Deploy the .war file like any other web application. If using Tomcat, copy the .war file to the Tomcat webapps folder, either manually or through the Tomcat web console (for example, http://<HIP Runtime REST API server >:8080/manager/html/lis).

Depending on how your web server is configured, you might need to restart the server after deploying the application.

The console of the web server displays whether the application started correctly. If the application did not start correctly, search the web server's log file for errors related to the hip-rest application.

Validating deployment

After you deploy the hip-rest application, by default, it runs with a context root of hip-rest.

{
version: "1.0.0",
status: "OK",
name: "HIP Runtime REST API",
up_time: "0 days, 0 hours, 0 mins, 25 secs"
}

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.

Running in a Docker container

Use these instructions to run the Link REST API in a Docker container. These instructions apply only to the Linux platform.

rest_docker.sh start

If you want to invoke the API on a different port (default 8080), modify the rest_docker.sh script. For example, to use port 4444, change the docker run command to -p 4444:8080.