Domino REST API for
Domino Administrators
OpenNTF
February 15, 2024
Heather Hottenstein
Matt Munse
Copyright © 2024 HCLSoftware Limited | hclsoftwareu.hcltechsw.com

Heather Hottenstein⮚ Technical Advisor⮚ heather.hottenstein@hcl-software.com

2Matt Munse● Manager of the Volt MX Go Design Import team● Manager of Volt MX Go L3 Support● Over 20 years of industry anddevelopment experience● matt.munse@hcl-software.com

3What’s up for today⮚ What is the Domino REST API⮚ What does this have to do with an admin⮚ Installing⮚ What gets installed⮚ How does it work
⮚ Port considerations⮚ Post installation configuration⮚ How to use it⮚ Where to find out more

4

What is the Domino REST API

55

What is the Domino REST API

6

I’m an admin…

7

Installing DRAPI⮚ https://my.hcltechsw.com• Domino – Tools, Connectors, Integrators – Domino REST API• Docker, Windows, Linux• V12 vs V14➢ Flexnet: HCL Domino⮚ Domino_REST_API_V1.0.9_R14_Installer.tar.gz• 7-Zip

my.hcltechsw.com• tar -xvzf domino_rest_api_v1.0.9_r14_installer.tar.gz -C c:\Domino✔ restapiInstall-r14.jar⮚ Windows Command Prompt – Run as Administrator

8

Install Commandjava -jar c:\domino\restapiinstall-r14.jar -d="c:\domino\data" -i="c:\domino\data\notes.ini" -r=“c:\domino\restapi"-p="c:\domino" –a-d = Domino data folder-i = File path and name of notes.ini-r = File path for Domino REST API library files-p = Domino program directory-a = Accept

Tech tip – run java explicitly from “c:\domino\java\bin\java.exe”

9Installed Components

10Server Task restapi

11DRAPI Basics• keepconfig.d folder• Overlay File System• Base configuration then keepconfig.d JSON
configuration files• Alphabetical order matters

12

DRAPI Ports• Data Port – 8880
• Main port used by the Domino REST API. Default authentication uses the user name and Internet password of theperson document.
• Healthcheck Port – 8886
• Used to verify whether Domino REST API is up using the /health endpoint. It has its own functional account that does
not provide access to other ports.
• Management Port – 8889
• Provides access to the Domino REST API runtime behavior, such as current config (/config), runtime info (/info) orDomino REST API shutdown/restart. Recommended that the port is blocked and accessed only from localhost. It has
its own functional account that does not provide access to other ports.
• Prometheus Port – 8890
• Provides metrics in Prometheus format. It has its own functional account that does not provide access to other ports.

13

DRAPI Ports

Note: DRAPI does not use Domino’s HTTP or TLS cache14Configuration

Domino REST API

Configuration

Functional Accounts• Functional accounts defined in JSON

• All JSONs go to keepconfig.d• Shhhhh – It’s a secret16

Management Console17Java Web Token• Default – random, one Domino server

https://drapi.server.com:8880

credentials

JWT

JWT18

• Permanent JWT• Copy files to other Domino servers• Accept JWT from external provider

19

Let’s Dance

20

Configuring OAuth• Update oauth.nsf database ACL• Add server to OAuthAdmin role
• Create oauth JSON file
• keepconfig.d folder{"oauth": {"active": true,"database": "oauth.nsf","url": "http://rock.adventure.com:8880","authCodeExpiresIn": 120,"accessTokenExpiresIn": 3600,"refreshTokenExpiresIn": 525600}}

21

DRAPI Databases Configuration✔ Create LocalKeepAdmins group✔ Update DRAPI databases’ ACLs
⮚ Domino Keep Agent Scheduler✔ Default Reader, change to No Access✔ LocalKeepAdmins - Editor⮚ Domino Keep Oauth✔ Default Author, delete flag disabled⮚ Domino Keep Configuration✔ Default Reader✔ LocalKeepAdmins - Editor✔ Sign DRAPI databases

22

Exposing Domino Databases

23Schema, Scope, Oauth application

24

Using Admin UI to create Schema, Scope, Oauth Application

25

Dev to Prod Promotions

26

DRAPI and Domino Clusters⮚ Load balancer/proxy⮚ restapi on cluster members⮚ Replicate keepconfig.nsf and oauth.nsf

27

DRAPI Resources for learning more
⮚ HCLU Domino REST API for Domino Admins⮚ Discord domino-rest-keep | OpenNTF⮚ Domino Administrators - What You Need to Know About the Domino REST API blog series⮚ Power BII, Domino and Domino REST API by Theo Heselmans⮚ Welcome - HCL Domino REST API Documentation (hcltechsw.com)

28

Common Production Q&A➢ 413 Request Entity Too Large error when trying to POST an attachment to the Domino REST API➢ How to Upgrade the Domino REST API➢ How to add a corporate logo to the OAuth consent screen➢ How to enable the Domino Directory for Domino REST API access➢ How to create a Domino database using Postman and DRAPI➢ Can I use the same IdP between Domino and DRAPI with oidc-idpcat

Answers to these and more: Welcome - HCL Domino REST API Documentation (hcltechsw.com)2930hclsoftwareu.hcltechsw.com