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

前回、前々回とDomino REST APIの環境構築について触れてきました。

そして、今回は実際にHCL Domino REST API を触っていきたいと思います。

API を試すときはAPI Reference の画面やcurl なども使えますが、今回はPostman を利用しました。

Postman とは？

Postman はAPI 開発のためのコラボレーション・テストツールです。

UI ベースで様々なAPI を検証したり、API 開発を迅速に行うための機能が多く含まれています。

Postmanはデスクトップ版を使います。予め以下のURLからダウンロードしておきましょう。

https://www.postman.com/

Postman へHCL Domino REST API 仕様の取り込み

HCL Domino REST API はOpen API に準拠して開発、API ドキュメントが公開されており、以下のような画面から仕様を詳しく確認できます。

さらに、Open API Spec のJSON もダウンロードできるので、これをPostman に取り込むことで簡単にAPI リクエストを検証することができます。

Open API Spec のJSON ファイルをダウンロードしたら、Postman を立ち上げて、「Import」をクリックします。

これでファイルを取り込み

Postman Collection としてImport しましょう。

これでAPI 仕様に従って、リクエストサンプルが自動的にPostman の中で構成され、手軽にAPI の検証をスタートすることができるようになります。

Variables の設定

Postman Collection を構成したら、Variables で接続情報やログイン情報を構成しておきましょう。あとで手軽にそれぞれのAPI リクエストで使いませるようになります。

まず、環境をlocalhost のhttp に構築しているので、protocol を変更しておきます。

さらに認証に利用するためのuser とpassword を変数として追加しておきました。

それでは実際にAPI を試していきましょう！

Access Token を取得する

まずは何はともあれ認証・認可です。HCL Domino REST API はOAuth の認証・認可プロセスをサポートしており、 JavaScript Web Token (JWT) を利用して接続します。

JWT の取得は「openid-configuration」のページで確認できるように「authorization_code」をサポートしているのでこれを利用して取得する方法と

http://localhost:8880/.well-known/openid-configuration

「/api/v1/auth」エンドポイントを利用して、JWT を入手する方法の2種類があります。

今回は手軽に試すことができる後者の手法を使って接続していきます。

Postman Collection の「auth」→「POST Get JWT Session」をクリックし、リクエスト Body の値を以下のように書き換えます。

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"
}

するとレスポンスとして以下のようにbearer token が取得できます。その他有効期限やユーザー名、スコープの情報が取得できます。

{
    "bearer": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIQ0wgUHJvamVjdCBLRUVQIFJBTkRPTSIsInN1YiI6IkNOPUthenV5YSBTdWdpbW90by9PPXJlc3RhcGkiLCJpYXQiOjE3MTgxNzcyODAsImV4cCI6MTcxODE4NDQ4MCwiYXVkIjoiRG9taW5vIiwiQ04iOiJDTj1LYXp1eWEgU3VnaW1vdG8vTz1yZXN0YXBpIiwic2NvcGUiOiJNQUlMICREQVRBICRERUNSWVBUICRTRVRVUCBEb21pbm8udXNlci5hbGwifQ.sqfLtEqUhTHcjE3675Uv_9V20lPpoqr9TVdOFHgsE1E",
    "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"
}

取得したBearerToken もVariables に追加しておきましょう。名称はbarerToken にしておくと自動的に他のAPI リクエストでも使われるようになります。

Scope に含まれるSchema 情報を取得する

最初に予め設定したScopeおよびSchema の情報を確認してみましょう。

Scope の一覧取得は「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

このScope の名前を元に、dataSource のクエリパラメータを利用することで、Schema 情報を取得することができます。Schema 情報にはForm やView としてどのようなものが定義されているのかを識別することができ、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 にView の名前と利用するScope 名をdataSource のクエリパラメータに付与してリクエストするのがポイントです。

実際のドキュメントのCRUD操作ではほとんどのエンドポイントでこの「dataSource」というクエリパラメータが必要になるので注意しましょう。

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

これで以下のようにView を使ってデータが取得できました。

[
    {
        "@unid": "BF419E31B5B8052B48258512002F9274",
        "@noteid": 13794,
        "@index": "1",
        "@etag": "W/\" 5e4ba2c8\"",
        "$1": "2020-02-18T16:39:36+08:00",
        "last_name": "Aaronsohn",
        "first_name": "Kristoffer",
        "email": "[email protected]",
        "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": "[email protected]",
        "Color": "Aquamarine",
        "Pet": "White-bellied sea eagle"

以下のビューのデータが取得できているのがわかりますね。

ドキュメントを作成する

続いてForm の機能を使ってドキュメントを作成・更新・削除してみましょう。

ドキュメントの操作は「document」→「POST Create a new document for a specified form.」を使用します。POST リクエストですが、クエリパラメータにdataSource を指定するのを忘れないでください。

そして、Schema Management のForm の設定画面で指定した項目をもとに、リクエストボディでJSON のデータを組み立てます。この時にJSONのFormプロパティでForm 名を指定するのも忘れないようにしましょう。

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"
}

これで実際に以下のようなデータが作成できました！

ドキュメントの更新

ドキュメントの更新では「document」→「(unid)」→「PUT Perform an update on the document at the relevant mode」を利用します。Method 以外はドキュメントの作成と似ていますがURIに更新対象のUNIDを加え、かつクエリパラメータとして「Mode」を指定するのがポイントです。

Mode とはSchema Management のForm 設定部分で指定されている以下の要素のことです。Form はMode 毎で表示項目やRead Write の設定を切り替えることができるようになっています。

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!"
}

ドキュメントの削除

ドキュメントの削除は更新のメソッドが違うバージョンです。「document」→「(unid)」→「DELETE Delete the given document」を利用します。

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 のドキュメントデータを網羅的に取得することが可能です。

https://help.hcltechsw.com/dom_designer/10.0.1/basic/dql_overview.html

「query」→「Send a DQL query and get JSON documents back」を利用します。

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 Document のSchema にある「Root Type for QueryRequest」で仕様が確認できます。

おわりに

これで環境構築からREST API を触るところまで一通り実施できました！

手軽に利用できることがイメージできましたでしょうか？

とはいえ、実際にREST API を使って外部サービスとの連携などを実装していく場合は、スクラッチなどで対応する必要も出てくると思います。

そこでCData Driver を利用することで、手軽に他サービスとの連携が実装できます。

次回、最終回はこのREST API に対してCData Driver から利用する方法を紹介したいと思います。

関連コンテンツ