HCL Domino REST API Part 3: Postman から REST API を利用する


本シリーズ第3回目となるこの記事では、HCL Domino REST API の実践的な活用方法をご紹介します。

これまでに、Domino 環境のセットアップ（Part 1）とスキーマおよびスコープ設定の構成（Part 2）を行い、Notes アプリケーションのアクセスパラメータを定義することで、構造化されたデータ取得と安全な API インタラクションを実現しました。今回は、実際に API リクエストを実行し、Domino REST API を実践的に操作していきます。

API のテストには、API Reference 画面や curl を使用することもできますが、今回のデモでは Postman を使用しました。

Postman とは？

Postman は、API の開発、テスト、コラボレーションに適した強力なツールです。API テストを効率化し、開発プロセスを加速するさまざまな機能を提供しています。

今回のデモでは、デスクトップ版の Postman を使用します。以下のダウンロードリンクから事前にダウンロードしておいてください。

Postman をダウンロード

HCL Domino REST API の仕様を Postman にインポートする

HCL Domino REST API は OpenAPI 準拠で開発されており、そのドキュメントは公開されています。詳細は以下の画面からアクセスできます。

OpenAPI Spec JSON を使用して、Postman で API リクエストを素早くセットアップする方法は次のとおりです。

  • OpenAPI Spec JSON ファイルをダウンロードします。これにより、Postman で簡単に API リクエストを検証できるようになります。
  • Postman を開き、Import をクリックします。
  • ダウンロードしたファイルを選択してインポートします。
  • Postman Collection としてインポートします。
  • これにより、API 仕様に基づいたリクエストサンプルが Postman に自動的に設定され、すぐにテストを開始できます。

変数の設定

Postman Collection が設定できたら、Variables セクションで接続情報とログイン情報を設定しましょう。これにより、後続の各 API リクエストで簡単に再利用できるようになります。

まず、環境が localhost 上にセットアップされているため、プロトコルを HTTP に更新します。

次に、認証用の変数として user と password を追加します。

それでは、API をテストしてみましょう！

アクセストークンの取得

HCL Domino REST API にアクセスするには、認証と認可が不可欠です。この API は OAuth 認証・認可プロセスをサポートしており、JavaScript Web Token（JWT）を使用して接続します。

JWT を取得するには、openid-configuration ページで提供される authorization_code を使用できます。

デフォルトの localhost アドレス: http://localhost:8880/.well-known/openid-configuration

このデモでは、テストが容易なこの方法を使用します。

Postman で JWT を取得する手順

  1. Postman で、Postman Collection 内の auth → POST Get JWT Session に移動します。
  2. リクエストボディの値を次のように変更します。 
    POST /api/v1/auth HTTP/1.1
Host: localhost:8880
Content-Type: application/json
Accept: application/json
Content-Length: 62

{
  "password": "Password!",
  "username": "Kazuya Sugimoto"
}
  3. 実行すると、API は以下の情報を含むレスポンスを返します。
    • Bearer Token
    • 有効期限
    • ユーザー名
    • スコープ情報

    レスポンス例

    {
  "bearer": "xxxxxxxxxxxxxxxxx",
  "claims": {
    "iss": "HCL Project KEEP RANDOM",
    "sub": "CN=Kazuya Sugimoto/O=restapi",
    "iat": 1718177280,
    "exp": 1718184480,
    "aud": ["Domino"],
    "CN": "CN=Kazuya Sugimoto/O=restapi",
    "scope": "MAIL $DATA $DECRYPT $SETUP Domino.user.all"
  },
  "leeway": 5,
  "expSeconds": 7200,
  "issueDate": "2024-06-12T07:28:00Z"
}
  4. 取得した Bearer Token を Postman の Variables に追加します。"bearerToken" という名前にすると、後続の API リクエストで自動的に使用されるようになります。

スコープに含まれるスキーマ情報の取得

まず、事前に設定したスコープとスキーマの詳細を確認しましょう。

  • scopes → GET Retrieve lists of scopes available based on query を使用して、利用可能なスコープのリストを取得します。
  • リクエストを認証するために、先ほど取得した bearerToken を "Authorization" ヘッダーに含めます。

リクエスト例

GET /api/v1/scopes HTTP/1.1
Host: localhost:8880
Accept: application/json
Authorization: Bearer eyJ0eXAiO
  • スコープ名を取得したら、dataSource クエリパラメータを使用してスキーマ情報を取得できます。
  • スキーマ情報には Forms と Views が定義されており、REST API と連携するアプリケーションを開発する際の動的機能の強化に役立ちます。

リクエスト例

GET /api/v1/scope?dataSource=demoscope HTTP/1.1
Host: localhost:8880
Accept: application/json
Authorization: Bearer eyJ0eXAiOiJK

ビューを使用したドキュメントリストの取得

それでは、ビューを使用して実際のドキュメントを取得してみましょう。lists → {name} → Pulls in view data を使用して、ビュー経由でドキュメントを取得します。

重要なポイントは、URL に ビュー名 と スコープ名 を dataSource クエリパラメータとして両方含めることです。

ドキュメントの CRUD 操作を行うほとんどのエンドポイントでは、この dataSource クエリパラメータが必要なので、正しく指定してください。

リクエスト例

GET /api/v1/lists/Customers?dataSource=demoscope HTTP/1.1
Host: localhost:8880
Accept: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGci

レスポンス例

[ {
"@unid": "BF419E31B5B8052B48258512002F9274",
 "@noteid": 13794,
 "@index": "1",
 "@etag": "W/\" 5e4ba2c8\"",
 "$1": "2020-02-18T16:39:36+08:00",
 "last_name": "Aaronsohn",
 "first_name": "Kristoffer",
 "email": "kaaronsohnf5@goo.ne.jp",
 "Color": "Purple",
 "Pet": "Bandicoot, long-nosed"
},
 {
 "@unid": "ED877AE5B4A2065B48258512002F935B",
 "@noteid": 14718,
 "@index": "2",
 "@etag": "W/\" 5e4ba2cb\"",
 "$1": "2020-02-18T16:39:39+08:00",
 "last_name": "Abbe",
 "first_name": "Bogey",
 "email": "babbelk@artisteer.com",
 "Color": "Aquamarine",
 "Pet": "White-bellied sea eagle"
} ]

取得したデータは上記の構造化されたビューに表示され、一意の ID、名前、メールアドレス、その他の属性などの詳細が確認できます。

API でドキュメントを作成する

次に、Form 機能を使用してドキュメントを作成、更新、削除する方法を見ていきましょう。

ドキュメントを作成するには、document → POST Create a new document for a specified form 操作を使用します。POST リクエストに dataSource をクエリパラメータとして含めることを忘れないでください。

JSON リクエストボディを構築する際は、Schema Management Form 設定画面で指定された項目を参照してください。また、JSON の Form プロパティには Form 名を指定してください。

POST リクエスト例

POST /api/v1/document?dataSource=demoscope HTTP/1.1
Host: localhost:8880 Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJ

{
"Form": "Customer",
 "last_name": "Hello!",
 "first_name": "Kazuya"
}

このリクエストにより、次のデータが作成されます。

API でドキュメントを更新する

ドキュメントを更新するには、次のパスを使用します: document → (UNID) → PUT Perform an update on the document in the relevant mode.

プロセスはドキュメントの作成と似ていますが、1つの重要な違いがあります。更新したいドキュメントの UNID を URI に含め、mode をクエリパラメータとして指定する必要があります。

Mode とは、Schema Management Form 設定で定義された要素のことです。Form では、選択された mode に基づいて表示項目や読み取り/書き込み設定を調整できます。

リクエスト例

PUT /api/v1/document/BF419E31B5B8052B48258512002F9274?dataSource=demoscope&mode=default HTTP/1.1
Host: localhost:8880 Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiL

{
"Form": "Customer",
"last_name": "Hello Update!"
}

このリクエストは、指定された UNID と mode を使用して、Customer フォームの last_name フィールドを更新します。

API でドキュメントを削除する

ドキュメントの削除は、更新と似ていますが DELETE リクエストを使用します。特定のドキュメントを削除するには、次の形式を使用します。

エンドポイント

DELETE /api/v1/document/{unid}

リクエスト例

DELETE /api/v1/document/8DBCCA8A6B6FFE2700258B39004FC6F3?dataSource=demoscope&mode=default HTTP/1.1
Host: localhost:8880
Accept: application/json
Authorization: Bearer eyJ0eXAiOiJKV1Q

重要: ドキュメントを削除する前に、対象の Form/Mode の Formula for Delete Access が "@True" に設定されていることを確認してください。

DQL でクエリを実行する

特別なケースとして、Domino Query Language（DQL） を使用したクエリ実行を見ていきましょう。

DQL を使用すると、SQL に似たクエリ言語で Domino ドキュメントデータを効率的に取得できます。

Domino Query Language

DQL クエリを送信して JSON ドキュメントを取得するには、query エンドポイントを使用します。

POST /api/v1/query?dataSource=demoscope&action=execute HTTP/1.1
Host: localhost:8880 Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiL

{
"query": "form = 'Customer' and Color = 'Fuscia'",
"mode": "default"
}

一見すると、リクエストボディにどのパラメータを指定できるか分かりにくいかもしれません。しかし、API ドキュメントの Root Type for QueryRequest セクションを参照すると、詳細な仕様を確認できます。

まとめ

以上で、環境のセットアップから REST API の利用までの一連の流れが完了しました！

いかがでしたでしょうか。シンプルかつ効率的であることがお分かりいただけたかと思います。

ただし、REST API を外部サービスと連携する場合、接続を一から構築する必要があるかもしれません。このプロセスを簡素化するには、他のサービスとシームレスに統合できる CData HCL Domino ドライバーをご利用いただけます。

このシリーズの次回、最終回では、CData HCL Domino ドライバーを HCL Domino REST API で使用する方法をご紹介します: HCL Domino REST API Part 4: CData Tableau Connector を使用して Tableau から接続する

始める準備はできましたか？

HCL Domino 用ドライバーの詳細、または無料トライアルをダウンロード:

今すぐダウンロード

In this article

Related articles