This chapter describes the installation of Rest API and covers the following topics:
This section assumes you have already configured EFTLink following the instructions set out in the Oracle Retail EFTLink Framework Installation and Configuration Guide.
EFTLink Rest API will run with any version of Java from 1.8.The Rest API by default expects Java jre to exist in the folder location C:\jre
(on Windows) or /opt/jre
(on a Linux kernel).To change the default location of java you will need to update either include-eftlink-rest-api-windows.conf
or include-eftlink-rest-api-linux.conf
which are located in <installation directory>\wrapper\conf
.
Note: All files necessary, are already in place so long as you have completed the instructions set out in the Oracle Retail EFTLink Framework Installation and Configuration Guide. |
Out of the box, the Rest API will only allow SSL communication. However, you are required to setup a key store that includes a server certificate.
The certificate can be either a self-signed (for internal testing use only) or signed by known third party Certificate Authority (CA) vendor like Verisign.
See Creating a Key Store File with Self-Signed Certificate details below on how to create a self-signed certificate.
Once the eftlink-rest-api "keystore" file has been created, you will need to obfuscate the password (See Obfuscating Text using Jetty section below).
Once you have the obfuscated password, open the jetty.xml
file located in the root of the eftlink installation directory.
Replace the text ObfuscatedPasswordHere with your obfuscated password.
For example,
<New id="sslContextFactory" class="org.eclipse.jetty.util.ssl.SslContextFactory">
…
<Set name="KeyStorePassword">ObfuscatedPasswordHere</Set>
<Set name="KeyManagerPassword">ObfuscatedPasswordHere</Set>
<Set name="TrustStorePassword">ObfuscatedPasswordHere</Set>
…
</New>
Open a command terminal.
Navigate to C:\eftlink\keys or any other directory.
Execute the command below. The command will ask of your first and last name(Common Name or CN).
Enter the machine name or localhost. Populate the other details. The alias below, "restAPI_9_2020" can be anything.
The sample password below is "Password". You can use any password you desire for your key store and certificate. Just take note of them as we need to obfuscate them later.
The command will produce the key store file, eftlink-rest-api.keystore
on the current directory.
The output file needs to be copied in C:\eftlink\keys
if it's not there yet. Create the keys directory if needed.
Assuming that EFTLink is already installed at C:\eftlink, open a command terminal and navigate to C:\eftlink\lib.
Execute the command below. The parameter 'Password' is your desired password to obfuscate.
If Jetty is upgraded in the future, replace the filename(jetty-util-9.4.27.v20200227.jar) below.
java -cp jetty-util-9.4.27.v20200227.jar org.eclipse.jetty.util.security.Password Password
Sample output below. We are interested with the OBF version.
Password
OBF:1eam1lmn1hv41ink1uh21ugo1iku1hse1lj31e8w
MD5:2d6df80067293fb807d8adc12fa17650
This section describes how to install EFTLink Rest API as a service.
It is possible to install EFTLink Rest API as a windows service, using a third party wrapper. EFTLink is distributed with a version of Tanuki Software Limited Java Service Wrapper.
Follow the steps below on how to configure EFTLink to run as a Windows service.
Installing the Service.
From a command line (with administrative privileges) change to the root directory for EFTLink. For example, type cd /eftlink.
To install EFTLink Rest API as a window service, type eftlink-rest-api install
.
If there are problems during install, it is possible to remove the service by typing eftlink-rest-api remove
. This may be necessary if the service is previously installed in a different folder. The service may then be reinstalled at the correct location by entering eftlink-rest-api install
.
Once installed the service can be started and stopped from a command line:
Eftlink-rest-api start
Eftlink-rest-api stop
The service can also be controlled from the Windows Services Control Panel applet (Rest API).
Examine the log file Wrapper.log.
The log file can be found in the designated EFTLink folder\log\eftlink-rest-api_ wrapper.log
Installing, starting the service, stopping the service, and uninstalling the service are all briefly logged in wrapper.log, and this can be used to diagnose any problems.
It is possible to run EFTLink-rest-api as a service, using a third party wrapper. EFTLink-rest-api is distributed with a version of Tanuki Software Limited Java Service Wrapper.
Note: You may be required to give script file(s) execution rights. This can be accomplish by opening a terminal window and typing:
for example, |
Follow the steps below on how to configure EFTLink to run as a service.
Running EFTLink-rest-api.
From a terminal change to the directory for EFTLink.
For example, type cd /opt/eftlink.
To run EFTLink-rest-api as a service from a terminal type the following command sudo./eftlink-rest-api.sh start
.
To stop, check the status or to restart EFTLink-rest-api from a terminal, type one of the following commands: sudo./eftlink-rest-api.sh stop sudo./eftlink-rest-api.sh status sudo./eftlink-rest-api.sh restart sudo./eftlink-rest-api.sh condrestart
Examine the log file Wrapper.log.
The log file can be found in the designated EFTLink folder\log\eftlink-rest-api_ wrapper.log
Starting the service and stopping the service are all briefly logged in wrapper.log, and this can be used to diagnose any problems.
To trust the self-signed certificate in your browser:
Open your browser (for example, Chrome).
Ensure the REST API is running.
Navigate to https://localhost:8443/.
The browser will warn you that your connection is not private. Click on Advance.
Click Proceed to localhost (unsafe).
Disregard the 404 not found error.
Your browser is now ready to talk to the REST API using your code in the html file.