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.