HCL Domino REST API Part 1: How to set up the environment

CData offers drivers and connectors for HCL Domino, which support Domino 12 and higher via the HCL Domino REST API. This article is the first in a 4-part article series that goes over setting up and using the HCL Domino REST API. In this article, we review how to set up the environment for the HCL Domino REST API.

What is the HCL Domino REST API?

The HCL Domino REST API is a web service that connects HCL Domino databases, also known as Notes applications, with external applications via a web API.

Official Documentation: HCL Domino REST API Documentation

Internally, it uses the Domino C-API, which has been provided for a long time, and abstracts this API into an HTTP-based REST API. HCL Domino C API Documentation

The REST API itself is installed on the Domino Server or Notes Client (currently in beta) and is extended to be accessible via HTTP. The HCL Domino REST API features include CRUD operations on Notes application documents, file uploads and downloads, agent execution, and most other operations related to Notes applications.

Domino REST API System Requirements

Currently, Domino 12.0.2 or higher is required to use the HCL Domino REST API. The supported Domino versions may vary depending on the REST API version.

Official System Requirements: HCL Domino REST API System Requirements

Note: The module depends on the C-API and has a loosely coupled architecture, so while it is said to work on versions prior to 12.0.2, it will not be supported.

Environment Setup

The installation steps for the HCL Domino REST API differ depending on the platform. If you are installing it on an existing Domino Server, you will use a JAR file-based installer to configure only the REST API web service. However, the initial testing and getting started can be quite daunting.

Therefore, we will use the Docker version this time, which includes the Domino server and the Domino REST API functionality, making it easy to set up the environment.

For actual operation, you will need to consider other elements, such as HTTPS and Identity Provider, but we will omit those parts this time to focus on the REST API experience. This example is completed on a Windows machine with Docker installed. The following link goes over the full setup: Run HCL Domino REST API with a Docker image

1. First, you will need to gather the Docker image. You can get the Docker image from the HCL Software License and Download Portal (Flexnet) or the My HCLSoftware Portal.

2. Next, download the "Docker compose file" and the ".env" file, which contains the login information and domain information for the Domino Server to be constructed. Also, get the sample application "Demo.nsf" for testing the REST API. These can be downloaded here: HCL Domino REST API Downloads

   

3. After downloading, rename the files to "docker-compose.yml" and ".env" respectively. Open the command prompt and proceed with the Docker setup. First, load the downloaded Docker image.

   docker load -i Domino_REST_API_V1_Docker.tar.gz

   

4. Once loaded, the image name will be displayed. Use this image name to update the .env file. Refer to the following for information on each setting. This example is for setting up a new environment:

   # Admin - the person
   SERVERSETUP_ADMIN_FIRSTNAME=Kazuya
   SERVERSETUP_ADMIN_LASTNAME=Sugimoto
   SERVERSETUP_ADMIN_CN=Kazuya Sugimoto
   SERVERSETUP_ADMIN_PASSWORD=Password!
   # cert domain and org
   SERVERSETUP_ORG_CERTIFIERPASSWORD=password
   SERVERSETUP_ORG_ORGNAME=restapi
   SERVERSETUP_SERVER_DOMAINNAME=restapi
   # The server you setup
   SERVERSETUP_NETWORK_HOSTNAME=restapiserver.domino.acme.com
   SERVERSETUP_SERVER_NAME=restapiserver
   # Container info
   CONTAINER_IMAGE=hclcr.io/domino/restapi:1.0.8
   CONTAINER_NAME=domino-restapi
   CONTAINER_HOSTNAME=restapiserver.domino.acme.com
   CONTAINER_VOLUMES=domino_restapi_notesdata

5. After editing the .env file, start the container with the docker-compose command.

   docker-compose up

   

6. Additionally, it is not mandatory, but you can add the DNS specified in "SERVERSETUP_NETWORK_HOSTNAME" to the hosts file.

   127.0.0.1 restapiserver.domino.acme.com

7. Now, if you enter restapiserver.domino.acme.com:8880 in your browser, the HCL Domino REST API management screen will be displayed! The setup is successful.

   

Connecting from Domino Administrator

To access the Domino Server from the Domino Administrator or the Notes client, configure the HCL Notes client settings. To do this, enter the server name and server address of the environment you just set up to establish the connection.

Now you can access the Domino Server configured with Docker from the Notes client and Domino Administrator!

Conclusion

By using the Docker image, you can easily set up the Domino Server and Domino REST API environment. In the next article, we will try accessing the REST API using the environment we set up: HCL Domino REST API Part 2: Schema and Scope Setting.