HCL Domino REST API の使い方：②スキーマ・スコープ構成編

by 杉本和也 | 2024年06月19日

こんにちは。CData Software Japan リードエンジニアの杉本です。

本記事では前回に続いてHCL Domino REST API の使い方を解説していきます。

前回Domino Server・REST API の環境構築を行ったので、今回はNotes アプリケーションをAPI としてアクセスできるようにする設定、スキーマとスコープを構成していきます。

REST API のデザイン

さて、実際にAPI を触り始める前に、Domino REST API がどのようにNotes アプリケーション（.nsf・Notes Storage Facilityファイル）をAPI として公開するのか？　の概念をおさえておきましょう。

おそらく以下の画像が一番わかりやすいので引用します。

https://opensource.hcltechsw.com/Domino-rest-api/topicguides/understanding.html

Domino REST API は「スキーマ」という設定を用いてNotes アプリケーションに含まれるForm・View・Agentの各要素をAPI のデータモデルとして公開します。

Domino はいわゆるNoSQLライクなサービスであり、アプリケーションの中に様々なデータモデルが存在する形になりますが、REST API ではそのフォームの種類毎でデータモデルが決定されていきます。

また、フォームとモードと呼ばれる要素毎に読み取り・書き込み可能な項目も決まっていきます。

フォームとは別にビューも単体のデータモデリング要素として公開され、API アクセスが可能になります。

さらに、スキーマはScopeという要素を通じてAPI 公開されます。

Scope はそれぞれのOAuth アプリケーションで束ねられて、認証・認可プロセス時にScope 要求を受けて、利用できるスキーマの範囲を決定します。

ちなみにスキーマを公開するためのスコープとは別にベースとなるスコープとしてMAILや$DATA、$DERCRYPTなどがあり、メールや実データのアクセス制御をコントロールできるようになっています。

https://opensource.hcltechsw.com/Domino-rest-api/references/usingdominorestapi/scopes.html

対象のアプリ

今回API として公開するアプリは以下のような顧客情報を管理しているアプリ：Demo.nsf です。

以下のようなビュー・フォームが含まれています。

それではこのアプリにAPI アクセスができるように構成していきましょう！

Notes アプリケーションをREST API で公開するための設定

HCL Domino REST API は前述の通り、API 環境を構築しただけではNotes アプリケーションにアクセスすることはできません。

以下のような管理画面（8880ポート）から構成していきます。

まずConfiguration をクリックし

Domino Server のクレデンシャルを使ってログインします。

この画面を使ってスキーマやスコープ、OAuth アプリの構成を行っていきます。

スキーマの追加

最初にスキーマの構成を行います。

Schema Management の画面に移動し「＋Add Schema」をクリックします。

新しくスキーマを作るか、既存のスキーマをインポートするかが選べます。今回は新しく作成するので「Create Schema」を選択します。

以下のように接続しているDomino Server に存在するnsfファイルの一覧が表示されるので、今回公開するアプリケーションを選択し、「Schema Name」と「Description」を入力して追加します。

これで以下のようにスキーマの土台ができました。ちなみにデフォルト表示ではスコープが存在するスキーマだけに絞り込まれているので、「Only show schemas configured with scope」のチェックを外しておきましょう。

Form・View の要素をスキーマに追加する

ここからこのアプリケーションに存在するどのFormやView・Agenet をAPI として公開するのか？　の設定を追加していきます。

まずフォームとして今回は以下のCustomer フォームを追加します。

Domino Designer 上では以下の要素ですね。

default として構成するかどうかを聞いてくるので、default にしておきます。

次に対象のフォームを開き、このForm のどのフィールドをAPI として公開するのか？　の定義を追加します。

Customer フォームを開き、左側の項目一覧から「＋」ボタンをクリックして、フィールドを追加していきます。この際にField TypeやRead/Write の設定なども追加できます。

これでForm 要素の公開が完了です。

合わせてView も公開しておきましょう。Database Views タブに移動して、「Customers」のビューをActive にしておきます。

ビューはそのままでも利用できますが、エイリアスを指定して公開することも可能です。

なお、今回の記事では対象にしませんが、Agent もAPI から実行できるように公開することが可能です。

Scope の追加

Schema を構成したら、そのSchema にScope を付与してAPI としてアクセスできるようにします。

Scope Management の画面に移動し「＋Add Scope」をクリックします。

左のセクションから先程作成したDemoのスキーマを選択し、任意のScope Name とDescription を入力して、追加します。

これでAPI からリクエストする準備が整いました。

ちなみに簡易的な内部利用だけであれば、ここまでで十分かなと思いますが、OAuth アプリケーションとして複数のScopeを束ねたアプリケーションを登録し、外部サービスからの認証・認可プロセスも実装して利用することも可能です。

おわりに

これでようやくREST API を触るための準備が一通り完了しました。

次回、実際にREST API をPostman から実行してみます！

関連コンテンツ