こんにちは。CData Software Japan リードエンジニアの杉本です。
CData ではHCL Domino REST API と連携することが可能なHCL Domino Driver という製品を提供しているのですが、お客様からは「REST API ってどんなものなの？ どうやって環境構築するの？」という質問を頂くことが多くありました。
私も色々と調べてみたのですが、あまり日本語案内のドキュメントは多くなく、確かにこれだとREST API のキャッチアップだけでも大変なのに、環境構築や試しに繋いでみようと思ったレベルでも躓いてしまうかなーと思ったりでした。
そこで、本記事ではDomino REST API をはじめてみよう、触ってみようということで環境構築からAPI を実際にPostman で叩き、最終的にはCData HCL Domino Driver で接続するところまでを解説していきたいと思います。
HCL Domino REST API とは？
HCL Domino REST API はHCL Domino database、いわゆるNotes アプリケーションとWeb API ベースの接続を行い、外部アプリケーションからの連携を実現する Web Service です。
公式ドキュメント：HCL Domino REST API Documentation
https://opensource.hcltechsw.com/Domino-rest-api/index.html
内部では以前より提供されてきたDomino のAPIである C-API を利用しており、このAPI をHTTP ベースのREST API に抽象化してアクセスできるようにしています。
https://opensource.hcltechsw.com/domino-c-api-docs/
REST API 自体はDomino Server ないし Notes Client （現状はベータのようですが）にインストールして利用するものとなっており、そこにHTTP経由でアクセスできるように拡張するという仕組みになっています。
機能としてはNotes アプリケーションのドキュメントのCRUD 操作やファイルのアップロード・ダウンロード、エージェントの実行などNotes アプリケーションに関わるほとんどの操作がREST API を通じて実行できるようになっています。
Domino REST API システム要件
現在HCL Domino REST API を利用するにはDomino 12.0.2 以上が必要とのことでした。また、REST API バージョン毎でもサポートされるDomino バージョンに違いがあるようです。
https://support.hcltechsw.com/csm?id=kb_article&sysparm_article=KB0101789
ちなみに、モジュールとしては前述の通りC-API に依存し、疎結合なアーキテクチャになっているようで、一応12.0.2 以前のバージョンでも動作する、と書かれています。ただサポートの対象外にはなってしまうようです。
環境構築
それでは環境構築を進めていきましょう。
HCL Domino REST API はプラットフォームごとで導入の手順が異なります。
すでに存在しているDomino Server にインストールするのであれば、JARファイルベースのインストーラーを用いてREST API のWeb Service だけを構成する手順になります。
とはいえ、最初にテストしてとりあえず触ってみたいレベルだと敷居が高いですよね。
そこで今回はDomino サーバーとDomino REST API の機能が丸ごと含まれて、手軽に環境構築ができるDocker 版を利用していきたいと思います。
環境構築手順は以下のリンクの内容を参考にしました。私のWindows ノートパソコンにDocker をインストールして行っています。
ちなみに実運用を想定するのであれば、HTTPS化やIdentity Provider をどうするか、といった要素を考慮する必要がありますが、今回はREST API の体験に焦点を充てるため、その部分は割愛していきます。
https://opensource.hcltechsw.com/Domino-rest-api/tutorial/installconfig/docker.html
Docker イメージは「 HCL Software License and Download Portal (Flexnet) 」もしくは「My HCLSoftware Portal」から入手しておきます。
続いてDocker イメージを利用してコンテナを立てるための「Docker compose file」と構築されるDomino Server のログイン情報やドメイン情報などの設定値をまとめた「.env」ファイルをダウンロードしておきます。
合わせてREST API のテスト用にサンプルアプリケーションである「Demo.nsf」も入手しておきましょう。
https://opensource.hcltechsw.com/Domino-rest-api/references/downloads.html
ダウンロードが完了したら、docker-compose でそのまま実行できるようにファイル名を「docker-compose-primary.yml」→「docker-compose.yml」、「sample.env」→「.env」にそれぞれ変更します。
それではコマンドプロンプトを開いてDocker の準備を進めます。まずダウンロードしたDocker イメージを読み込ませましょう。
> docker load -i Domino_REST_API_V1_Docker.tar.gz
読み込みが完了すると、イメージ名が出力されます。
> hclcr.io/domino/restapi:1.0.8
そのイメージ名も用いながら、.env ファイルの内容を書き換えます。それぞれの設定値に関する情報は以下を参考にしてみてください。今回は新規環境を構成する形で記載しています。
https://opensource.hcltechsw.com/Domino-rest-api/tutorial/installconfig/docker.html#update-env-file
# 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
「.env」ファイルの編集が完了したら、docker-compose コマンドでコンテナを立ち上げます。
> docker-compose up
あと、必須ではありませんが、hostsファイルを開いて、「SERVERSETUP_NETWORK_HOSTNAME」で指定したDNSを追加しておきましょう。
> 127.0.0.1 restapiserver.domino.acme.com
これでブラウザに「restapiserver.domino.acme.com:8880」と入力すると、HCL Domino REST API の管理画面が表示されます！ うまく構築することができていますね。
Domino Administrator から接続する
合わせてDomino Administrator や Notes クライアントからアクセスできるよう、HCL Notes クライアントの設定を行います。
Domino Server 名とサーバーアドレスに先ほど構成した環境の情報を入力を行ってコネクションを確立します。
これで以下のようにDocker で構成したDomino Server へNotes クライアント・Domino Administrator からアクセスすることができるようになりました！
おわりに
このようにDocker イメージを利用することで手軽にDomino Server とDomino REST API の環境構築が行えます。
次回は実際に構築した環境を使って、REST API へのアクセスを試してみたいと思います
関連コンテンツ
