Binding
Concrete Specification（実装例）
Prerequisites（前提条件）
本プロトコルは HTTPS（TLS 1.2以上） を使用し、 REST形式のHTTPリクエスト/レスポンス により通信を行う。
エンドポイント：指定されたURIに対してHTTPメソッド（GET, POST, PUT, DELETE）を使用する。
データ形式：リクエストおよびレスポンスの本文はJSON形式とする。
Field Definitions（フィールド定義）
本プロトコルで使用される各フィールドの定義を記す。
各フィールドについて、以下の情報を記す。
フィールド名：プロトコル内で使用される名称
型：データ型（例：整数、文字列）
必須性：フィールドの利用条件
R = Required（必須）
C = Conditional（条件付き必須）
O = Optional（任意）
Request：リクエストにおいて使用される
Response：レスポンスにおいて使用される
説明：フィールドの意味や利用方法
Headerフィールド定義
通信時にはクライアントから以下のヘッダー情報の付与が必要となる。以下に記載のないヘッダー情報については任意となり、Web API転送モジュールは関知しない。
API-Key
String
C
✔
✔
クライアントアプリごとに払い出されたAPIKeyを指定する。
Authorization
String
R
✔
アクセストークンを指定する。例：Bearer < token >
X-TrackingID
String
C
✔
✔
✔
リクエストのトレーシングを行う一意なIDを指定する。クライアント側で指定されない場合はWeb API転送モジュールでUUIDを自動採番する。連携する機能によっては必須項目となる。（例：クリアリング・ペイメントとの連携時）
X-ODS-xxx
String
O
✔
✔
ODS内の制御用の拡張ヘッダ。例としてデータスペースコンプリメンタリサービス(DCS)の一つである精算決済サービスにおけるログを用いた整合性確認の用途がある。xxxには任意の文字列を記載。（例：X-ODS-UserId）
Payloadフィールド定義
Web API転送モジュールは透過的APIゲートウェイ方式を採用しており、ペイロード情報についてはデータ提供者が提供するAPIの仕様に依存するため、詳細な仕様については、該当するサーバー（データ提供者）のシステム仕様書を参照すること。
なお、エラー発生時の応答については以下のペイロード(JSON形式)が返却される。
code
String
[prefix] {Error Status}
prefixを含むエラーコード。prefixは下記のとおり。 ・dataspace: Web API転送モジュールでエラーが発生した場合 ・auth: 認証認可関連のエラーが発生した場合
message
String
{Error Message}
具体的なエラーメッセージ
detail
String
{Timestamp}
タイムスタンプ（ISO 8601 の UTC 形式）
出力例
Functional Description（機能詳細）
Web API転送モジュールは、透過的APIゲートウェイ方式を採用し、ルーティング機能のみに限定しており、ペイロード情報の解析やモデル変換の機能は提供していない。また、Web API転送モジュールはデータ利用者のアプリケーションとデータ提供者が所有するシステム間通信に介在し、アイデンティコンポーネントと連携したトークン検証および認可制御のためのPEP（Policy Enforcement Point）機能を提供する。
トランザクションレイヤが提供する機能は以下の通りである。
ルーティング
透過的APIゲートウェイとして、連携サービスへのルーティング機能を提供する。
ルーティングのルールを"ルート"として登録し、データ利用者とデータ提供者を仲介する。各ルートは、リクエストの条件（パス、メソッド、ヘッダなど）に基づき、転送先システムのAPIへリクエストを振り分ける。この仕組みにより、ルート設定を変更することで、転送先や条件を容易に追加・更新できる動的なルーティングを実現する。また、ルーティングの際には、Web API転送モジュールとして必要な処理(例：リクエストヘッダーにX-TrackingIDが含まれていない場合は、新規にUUIDを採番する、ヘッダーの内容を書き換える等)を実施する。
認証制御
クライアントの認証を行う
クライアントを認証する方式として以下の2つの認証を実施する。 ・APIキー認証 リクエストヘッダー「API-Key」の検証をWeb API転送モジュール内で実施する。 ・OAuth 2.0 / OpenID Connectトークンイントロスペクション リクエストヘッダー「Authorization」のアクセストークンの検証をIdentity & Trust（L3）と連携して行う。検証の結果、無効または期限切れの場合はHTTPレスポンスステータスコードを「401 Unauthorized」として、JSON形式のエラーレスポンスを返却する。認証制御をWeb API転送モジュールと分離することで、責務が明確になり保守性が向上し、認証方式の変更や追加があってもゲートウェイへの影響を最小化できる。
認可制御
認可制御におけるPEPとして動作する。
PEP（Policy Enforcement Point）として、PDP（Policy Decision Point）であるIdentity & Trust（L3）と連携して認可制御を実現する。Identity & Trust（L3）が持つ認可機能（OpenFGA）とはAuthZEN APIで連携する。なお、認可制御はユースケースによって要否が異なるため、設定によってON/OFF制御を可能とする。
ロギング
ODS基盤における保守運用のために必要なログを出力する。
Web API転送モジュール内処理の追跡性確保のための情報（ルーティング情報やトラフィック情報等）やデータスペースコンプリメンタリサービス（DCS）との連携のために必要な情報をログとして出力する。ロギング対象の情報は以下の通りである。 【リクエスト時】 ・リクエスト送信元情報 ・リクエスト転送先情報 ・リクエストAPI情報 ・リクエスト受信時間 ・リクエスト送信時間 ・X-TrackingID ・X-ODS-xxxヘッダの情報 【レスポンス時】 ・レスポンス受信時間 ・レスポンス送信時間 ・X-TrackingID ・ステータスコード
ルート情報永続化
Web API転送モジュールのルーティングに必要なルート情報を永続化する。
・ルート情報のDBへの永続化 ルート情報が再起動等でクリアされないようにDBに格納することで、永続化する。永続化された情報はWeb API転送モジュール起動時にルート情報としてロードされる。 ・ユースケース毎にルート情報を管理可能 1つのDBを複数のユースケース（Web API転送モジュールはユースケース毎に用意）で共用したい場合、ユースケース毎のルート情報はDB（PosgreSQL）のデータベース内にスキーマを分けることで管理する。Web API転送モジュールからは、DBの接続情報として参照するスキーマを指定し、ユースケース毎のルート情報を取得する。
ファイル転送
Web API転送モジュールでファイル送受信を行う。
・ファイル取得 連携先システムからWeb API転送モジュールを介してファイル形式のデータを取得できる。データサイズは数MB程度を想定。 ・ファイル転送 連携先システムに対してWeb API転送モジュールを介してファイル形式のデータを転送する。データサイズは数MB程度を想定。
移行性
コンテナ基盤で動作する。
コンテナ基盤で動作し、クラウドサービス等に依存しない。
Sequence Diagram（シーケンス図）
シーケンスの説明
1
クライアント（データ利用者）は、データ提供者の API を実行するため、Web API転送モジュールに対して HTTPリクエストを送信する。
2
Web API転送モジュールは、受け取ったリクエストに対してAPIキーチェックを行う。APIキーチェックを通過した場合、トークンの正当性を確認するため、アイデンティティコンポーネントの「トークンイントロスペクション」エンドポイントへ HTTPリクエストを送る。なお、リクエストヘッダーにX-TrackingIDが含まれていない場合は、新規にUUIDを採番する。
3
アイデンティティコンポーネントはトークンを検証し、その結果（有効性・スコープなど）をWeb API転送モジュールに返す。
4
Web API転送モジュールはさらに、クライアントが要求している操作が許可されているかを確認するため、「認可チェック」エンドポイントへ HTTPリクエストを送信する。
5
アイデンティティコンポーネントはポリシーに基づいてアクセス権を評価し、認可結果をWeb API転送モジュールに返す。
6
認証・認可が通過すると、Web API転送モジュールはデータ提供者サーバーの API エンドポイントへ HTTPリクエストを送る。
7
サーバー（データ提供者）は要求された処理を実行し、その結果をWeb API転送モジュールへ返す。
8
Web API転送モジュールは受け取った API 結果をクライアントにそのまま返却し、クライアントはデータを取得する。
最終更新