Skip to main content
Skip table of contents

Install and configure Operational API

Overview

The Operational Interface (OAPI) is a web service which provides an HTTP REST-like interface to Data Management. OAPI is deployed as a web application in the Apache Tomcat web server. This section describes how to install, configure, and deploy the OAPI.

Requirements

  • Windows or Linux

  • Java 17

  • Apache Tomcat 10.1.x

Download Tomcat

Download the latest available 10.1.x version of Tomcat’s “core” binary distribution.

  • For Windows, download the Windows Service Installer

  • For Linux, download the GZIP’d tarball

Comprehensive instructions for installing and configuring Tomcat are available on the Tomcat site; this document will highlight essential details.

Install Tomcat

Windows

On Windows, Tomcat will be installed as a service, so the installation program must be run as an
Administrator. The installation program presents a sequence of straight-forward steps; the default options are generally acceptable.

  1. Start the Tomcat installation program.

  2. On the Choose Components step, accept the defaults.

  3. On the Configuration step, provide details for configuring access to the Tomcat Manager.

  4. Specify a username and password, and select the manager-gui role. Please note the username and password are unrelated to OS usernames and passwords. Note the username and password; you’ll use them when viewing the Tomcat Manager page.

  5. For the JVM step, browse to your Java 17+ installation.

  6. For the Install Location step, accept the default.

  7. In the final step, select the option to "Run Apache Tomcat".

Linux

On Linux, it is easiest to install Tomcat in your home directory, but you may install it in any directory you choose. Once Tomcat is started, it will be accessible by all users on the Linux machine or by any external user.

A startup command runs Tomcat in the background in nohup mode, so it will continue to run once you logout and it will not stop until the stop command is run.

Start with the downloaded Tomcat binary distribution file for Linux.

  1. Make your current working directory the location where you will install Tomcat.

  2. Expand the Tomcat distribution file with the following command to install Tomcat in a new directory named apache-tomcat-10.1.18:

    CODE
    $ tar xvf apache-tomcat-10.1.18.tar.gz
  3. Define the CATALINA_HOME environment variable, and assign it to the Tomcat installation directory. For example:

    CODE
    $ export CATALINA_HOME=/path/to/install/apache-tomcat-10.1.18

Configure the Tomcat Manager

The Tomcat Manager enables you to deploy web applications. Tomcat no longer provides a default Manager username and password so you must configure these yourself.

Windows

This was done during Step 3 of the installation, Install Tomcat>Windows.

Linux

On Linux, you must add a user to the $CATALINA_HOME/conf/tomcat-users.xml configuration file. The username is used exclusively for accessing the Tomcat Manager; it needn’t match any existing Linux username.

In a text editor, open tomcat-users.xml and add the following line with an appropriate username and password:

XML
<user username="..." password="..." roles="manager-gui" />

Start Tomcat

Windows

Check the Windows Service Manager. Tomcat should be running; if not start it.

Linux

Start Tomcat by running command:

CODE
$CATALINA_HOME/bin/startup.sh

You can stop Tomcat by running command:

CODE
$CATALINA_HOME/bin/shutdown.sh

Verify Tomcat is operational

Open a browser and browse to http://localhost:8080. This should display the Tomcat home page. Next, verify access to the Tomcat Manager:

  1. Select the Manager App button.

  2. When prompted for credentials, enter the username and password you configured earlier.

  3. You should see a page that looks similar to the following:

oapi-tomcat.png

Optionally configure Tomcat for HTTPS

The OAPI works via HTTP or HTTPS. To communicate with the OAPI using HTTPS:

  1. Create a keystore with a self-signed security certificate.

  2. Copy the keystore into the Tomcat configuration directory.

  3. Stop Tomcat.

  4. Edit the Tomcat configuration file server.xml to turn on HTTPS and use the installed keystore.

  5. Start Tomcat

Windows Note:

You will create a keystore using the Java keytool command. In Windows, the keytool command is not normally in the command path, however, it is in the bin directory of the Java installation directory. For example, C:\ProgramFiles\Java\jre17\bin\keytool.exe. In the example below, only the name keytool is used; you may need to enter the complete pathname to run it.

Create a keystore

  1. Using the Java keytool command, create a keystore with a self-signed certificate with the following owner information:

JAVA
Common Name: CN="OAPI"
Organization: O="RedPoint Global, Inc."
Country: C="US"
  1. Start a command window and go to your home directory.

  2. Run the following command with the given responses.

JAVA
prompt: keytool -genkey -alias tomcat -keyalg RSA
Enter keystore password: changeit
Re-enter new password: changeit
What is your first and last name? OAPI
What is the name of your organizational unit? <RETURN>
What is the name of your organization? RedPoint Global, Inc.
What is the name of your City or Location? <RETURN>
What is the name of your State or Province? <RETURN>
What is the two-letter country code for this unit? US
Is CN=OAPI, ... C=US correct? yes
Enter key password for <tomcat>
(RETURN if same as keystore password): <RETURN>

This will create file .keystore in your home directory, for example:

  • Windows: C:\Users\myusername\.keystore

  • Linux: /home/myusernanme/.keystore

  1. Verify the keystore file and certificate with the following command:

CODE
prompt: keytool -list -v
  1. Next, you must install the keystore file by copying it into the Tomcat installation’s conf directory. Copy the keystore to:

    • Windows: C:\'Program Files'\'Apache Software Foundation'\'Tomcat 10.1'\conf\keystore

    • Linux: $CATALINA_HOME/conf/keystore

Edit Tomcat configuration

To enable Tomcat to use HTTPS with the created keystore, you must add a new XML element to configuration file server.xml. It is located at:

  • Windows: C:\'Program Files'\'Apache Software Foundation'\'Tomcat 10.1'\conf\server.xml

  • Linux: $CATALINA_HOME/conf/server.xml

  1. Open server.xml with a text editor. Inside are several <Connector> elements.

  2. Add the following element as a sibling of the other <Connector> elements:

XML
<!-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 →
<Connector
protocol="org.apache.coyote.http11.Http11NioProtocol"
port="8443" maxThreads="200"
scheme="https" secure="true" SSLEnabled="true"
keystoreFile="conf/keystore" keystorePass="changeit"
clientAuth="false" sslProtocol="TLS"/>
  1. Save the file and exit.

Verify HTTPS is operational

  1. Start Tomcat. Open a web browser and browse to https://localhost:8443.

  2. The browser will most likely issue a warning that Tomcat has presented a self-signed certificate, state that the server is not secure, and ask if you wish to proceed.

  3. Once you dismiss the warning, you will see the Tomcat home page.

Creating a certificate signed by a certificate authority is beyond the scope of this document.

Deploy the OAPI web application

  1. Download oapi-implementation-3.0.6.6.war and rename the file to oapi.war.

  2. In a web browser, browse to the Tomcat Manager.

  3. Under the WAR file to deploy section, select Choose File.

  4. Navigate to the directory containing oapi.war and select it.

  5. Select Deploy.

After a moment, Tomcat will deploy the OAPI web application and list it as /oapi in the Applications table.

Verify the OAPI is operational

In a web browser, browse to http://localhost:8080/oapi/v1/ping. The response should be simply PONG.

View the Swagger API documentation with URL: http://localhost:8080/oapi/swagger-ui/index.html or go to http://localhost:8080/oapi/ and select the API Documentation link.

Define system configuration parameters

Make sure to set the appropriate system configuration parameters in Redpoint Interaction (RPI):

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.