Skip to content

Installation and configuration

Installation

System requirements

Before performing the installation, make sure to check the System requirements.

Download Domino REST API

Note

Starting Domino REST API version 1.0.9, there will be four install files available for download. There will be two install files for Domino 12 and two install files for Domino 14. For example:

For Domino 12

  • Domino_REST_API_V1.0.9_R12_Docker.tar.gz
  • Domino_REST_API_V1.0.9_R12_Installer.tar.gz

For Domino 14

  • Domino_REST_API_V1.0.9_R14_Docker.tar.gz
  • Domino_REST_API_V1.0.9_R14_Installer.tar.gz

Important

via My HCLSoftware Portal

  1. Go to My HCLSoftware Portal link image.

  2. On the landing page, click Sign in.

  3. On the sign in page, login using your credentials.
  4. On the Software Downloads page, click HCL Domino.
  5. On the HCL Domino page, go to the Tools, Connectors, and Integrators section and click Domino REST API.
  6. Under All Releases, click the release version that you want to download.
  7. Under Downloads, click the download icon corresponding to the file that you want to download.

via HCL Software License and Download Portal

Option 1

  1. Go to HCL Software License and Download Portal link image.

  2. On the sign in page, enter your username and click Next. The License & Download Portal home page opens.

  3. In the Your Downloads pane, scroll to find and then select HCL Domino. The Download Packages page opens.
  4. On the New Versions tab, select the HCL Domino REST API version that you want to download.
  5. On the Software Terms and Conditions page, click I agree for the EULA Agreement.
  6. On the Downloads page, select the files to download and then click Download Selected Files, or click the file name of the file you want to download in the File Name column.

Option 2

  1. Go to HCL Software License and Download Portal link image.

  2. On the sign in page, enter your username and click Next. The License & Download Portal home page opens.

  3. Go to Downloads → Search Downloads.
  4. On the Download Search page, enter HCL Domino REST API in the Search for field, and then click Search.
  5. Select the HCL Domino REST API version that you want to download from the search result.
  6. On the Software Terms and Conditions page, click I agree for the EULA Agreement.
  7. On the Downloads page, select the files to download and then click Download Selected Files, or click the file name of the file you want to download in the File Name column.

Tip

If you downloaded the Domino REST API Installer, extract the .tar.gz file before installing.

Perform the following based on your OS:

  • macOS / linux - execute the following command: tar xvf ./Domino_REST_API_V1_Installer.tar.gz --no-same-owner --no-same-permissions

  • Windows - Newer versions of Windows supports extracting .tar.gz through the Explorer, also most 3rd party compression utilities supports extracting .tar.gz -- Consult your 3rd party tool documentation for more information.

You may ignore any warning starting with Ignoring unknown extended header keyword while decompressing the tar.gz file.

Domino REST API can be installed on:

All platforms use a Java-based installer, except Kubernetes or Docker, which uses a container (colloquial referred to as Docker) image. You can download the installer and the Docker image from your HCL Software License and Download Portal or My HCLSoftware Portal account. For any questions, contact your HCL reseller.

You did shut down Domino, did you?

It is strongly recommended, that you shut down your Domino server before running the installer. The installer updates the notes.ini which could conflict with a running Domino server

The installer requires a series of parameters:

[sudo] java -jar restapiInstall.jar [-ahnsyV] -d=<dataDir> -i=<notesIni> -r=<restapiDir> -p=<programDir>

Important

  • Starting Domino REST API version 1.0.7, the installer jar filename now includes the Domino version, for example, restapiInstall-r12.jar.
  • Starting Domino REST API version 1.0.9, there will be two installer jar files:
    • For Domino 14, use restapiInstall-r14.jar.
    • For Domino 12, use restapiInstall-r12.jar.

Tip

Notes and Domino install a JVM on your computer. You can and should use it to install.

  • On Linux, /opt/hcl/domino/notes/latest/linux/jvm/bin
  • On Windows, <Notes installation directory>/jvm/bin (example: Program Files/HCL/Notes/jvm/bin)

You can also verify the Java version by opening the command prompt, going to the installation location, and then typing java -version.

Explanation of parameters

Short Full parameter Mandatory Description
-d --dataDir=<dataDir> ✓ Directory of your HCL Notes or Domino data.
-i --ini=<notesIni> ✓ HCL Notes/Domino notes.ini file.
-r --restapiDir=<restapiDir> ✓ Directory to install the Domino REST API files into.
-p --programDir=<programDir> ✓ Directory where HCL Notes or Domino is installed.
-u --upgrade Performs an upgrade from a previous version. Upgrade will remove known
program files and libraries from the rest API directory and install the new
version into the same directory.
-f --forceUpgrade Performs an upgrade without regard to the previous version. If an unknown
version or unexpected files are found in the rest API directory, this option will delete
the entire contents of the rest API directory and subdirectories first before installing
the new version.
-a --accept Automatically accept terms & conditions.
-h --help Show this help message and exit.
-n --noIniUpdates Install the files, show updated ini entries but don't write them out. You are then responsible to update the notes.ini yourself, especially adding restapi to servertasks to auto-start the REST API
-o --oneTouchInstall If installing restapi as part of a Domino One Touch Install, use this option
to prevent checking for Notes / Domino directories and notes.ini.
-y --dryRun Do not actually copy or alter files and settings.
-s --skipDirectoryCheck Skips the checks if the program and data directories
contain Notes or Domino.
-V --version Print version information and exit.

Installation return codes

Code Explanation
0 Operation completed with no known error.
1 License not accepted.
2 Installation type could not be determined or is not supported.
3 Check for / creation of installation directories failed.
4 Extraction of Domino REST API binaries and JARs failed.
5 Creation of start script/cmd failed.
6 Update of notes.ini failed.
7 Upgrade aborted by user (missed the final A before proceeding with the upgrade).

To address the issue, make sure to type A before pressing [Enter] to proceed with the upgrade.

Tip

You can use a response file (see below) to provide the parameters.

Using a response file

Instead of providing all parameters on the command line, the Domino REST API installer can be called using a response file:

[sudo] java -jar restapiInstaller.jar @responses.txt

The file contains one parameter per line. Lines starting with # get ignored. Variables with \ need to be escaped \\:

# Sample of an installer response file
--dataDir=D:\\Domino\\data
--ini=D:\\Domino\\data\\notes.ini
--restapiDir=C:\\Program Files\\HCL\\restapi
--programDir=C:\\Program Files\\HCL\\Domino
--accept

Configuration & Security

Domino REST API is preconfigured with settings that allow you to get started right away. It will run on http (not https) on port 8880. However, you should familiarize yourself with all configuration parameters and security settings before you deploy into a production environment.

Tip

Domino REST API honors all Domino access control mechanisms and doesn't allow anonymous access. For more information, see Access Control.

Uninstall

Follow this guide to remove Domino REST API from your system.