共通 API 基盤の構成検討

結論

「理想」は条件で変わります。以下は、いただいた前提(A・B が稼働中で C を新規に作る、プロダクトごとにチームがある、Platform Engineering Team が基盤を持つ、横断集計は各プロダクトの画面に出す)で理想になる構成です。前提が変わった場合の理想は、各章の条件表と第 12 章にまとめています。

前提と、判断を分ける条件

いただいた情報のうち、構成を決めるのは次の4点です。A は「1顧客 = 1 client、その下に複数 project」、B は「1顧客企業 = 1 tenant、その tenant に A の client が複数つながる」、C は管理単位が未定、ユーザーは各プロダクトが別々に持つ。

このほかに、分かっていないことで理想が変わる条件があります。この解説では下表の「今回の想定」で書き、変わった場合の構成は各章に書きます。

「共通 API 基盤」という発想は正しいか

「共通 API 基盤」という言葉は、少なくとも4つの別の構成を指します。どれが正しいかは条件で決まり、今回の前提では ③ が理想です。① と ④ は条件つきで ③ と組み合わせ、② は今回の前提では選びません。

A↔B だけの今から ③ で始める理由

① でも A↔B はつながります。ただし ① でも必ず作ることになる2つ、「呼び出し元のサービスの認証」と「どの B tenant がどの A client のデータを使ってよいか」は、C が加わると作り直しになります。この2つは最初から土台に置きます。API Center や APIM workspace の整備などは、C の着手に合わせて足しても構いません。土台は最小から始めて、使われる分だけ育てます(Team Topologies の Thinnest Viable Platform)。

最終形の全体構成

認証の統合まで終わった最終形です。途中の段階は第 9 章に分けて描きます。青は各プロダクトチーム、緑は Platform チーム、紫は認証、橙は分析の部品です。

顧客組織の台帳: client と tenant の対応付け

A は「契約ごとの client」、B は「企業ごとの tenant」です。どちらかの単位に揃えるのではなく、上位に Organization(顧客組織)を置き、各プロダクトの単位を Organization に対応付けます。プロダクト間でデータを使う許可は Grant として別に持ちます。

// 台帳の最小のデータ(業務データは入れない)
Organization   (org_id, name, parent_org_id)
ProductAccount (org_id, product, account_id)        // product=A なら client_id、B なら tenant_id
Grant          (grant_id, grantee_product, grantee_account_id,
                source_product, source_account_id, scopes[],
                status, requested_by, approved_by, approved_at, expires_at, revoked_at)
Membership     (org_id, user_id, role)              // 共通 IdP を入れる Phase 2 以降

接続許可(Grant)の成立のさせ方

ユーザーがプロダクトごとに別々の現状でも、Grant は作れます。B で申請し、データの持ち主である A client の管理者が A にログインして承認する流れにします。A のログインで承認者の本人確認をするので、共通 IdP を待たずに成立します。

プロダクト間の API 呼び出し

B の画面で、接続済みの a-101 の project 一覧を出す場合です。B は社内の Entra ID でサービスとしてのトークンを取り、APIM と A の両方が「b-9 は a-101 を読んでよいか」を台帳で確かめます。リクエストに書かれた tenant ID を、確かめずに信じることはしません。

「どの顧客として呼ぶか」の伝え方は3通りある

Phase 1〜2 では、A は B のユーザーが誰かを知りません。そのため連携で効く権限は「組織として許可したか」(Grant)までです。B の特定のユーザーには a-101 の一部の project しか見せない、という要件がある場合は、共通 IdP 統合後の P1 まで待つか、Grant の範囲を project 単位にして B 側で絞ります。

同期 API とイベントの使い分け

「データ取得・登録・更新」は同期 API で行います。一方で、他のプロダクトで起きた変化を知るために相手の API を定期的に呼ぶ(ポーリング)と、呼び出しが増え続けます。「起きたこと」はイベントで知らせ、大量の集計は分析基盤で扱います。

顧客に公開する API

「各プロダクトのユーザーはそのプロダクトの API を使える」という要件は、最終形では次の形にします。入口のドメインとポータルは1つ、API はプロダクトごと、認証方式は全プロダクト共通です。

認証基盤の変遷(Phase 0〜4)

段階ごとに、変える対象を1つに絞ります。サービス間 → 新規プロダクト → 既存ユーザー → 旧資産の削除の順です。タブで各段階の構成を切り替えられます。橙の枠がその段階で変わる部品です。

共通 IdP の製品は「顧客組織の機能を IdP に求めるか」で決まる

既存ユーザーの移し方

権限はどこに置くか

認証の統合と権限の統合は別の話です。「誰か」(認証)と「どの組織に属し、どのプロダクトを契約し、プロダクト間で何を許したか」は共通化し、「プロダクトの中で何ができるか」は各プロダクトに残します。

認可エンジンを後から入れる可能性に備えるなら、API から台帳への問い合わせを OpenID AuthZEN Authorization API 1.0(2026-01 に最終仕様)の形に寄せておくと、問い合わせ先を差し替えやすくなります。OpenFGA は CNCF Incubating(2025-10)です。Azure にはこの種のマネージドサービスがないので、自前で運用することになります。

横断集計: 集計 API か、集計用データの取得か

「集計してデータを返す API」と「集計のためにデータを取得する仕組み」は、別の層の話です。画面が呼ぶのは集計済みの値を返す API、材料を運ぶのは分析基盤への複製で、両方が要ります。避けるべきなのは、プロダクト間の API で生データを運んで、使う側で集計することです。

鮮度の決め方

指標ごとに次の順で判断します。既定は「5 分以内」とし、画面には必ず「◯時◯分時点」を表示します。

条件を切り替えて、既定から変わる点を見る

当てはまる条件にチェックを入れると、第 0 章の構成から変わる点が表示されます。チェックした内容はコピーできるので、質問するときに貼り付けてください。

Azure で作るときに先に知っておくこと

構成に影響する制約だけを挙げます。いずれも 2026-09-13 時点の Microsoft Learn などで確認しました。

まだ決まっていないこと

次の項目が決まると、この解説のうち条件つきで書いた部分がどちらかに確定します。