既存システムをAPIで生かす：モダナイゼーションを進める連携境界の設計
基幹システムを使い続けながら、新しいWeb画面や外部サービスを連携させたい。こうしたモダナイゼーションでは、既存の機能をAPIとして提供する方法が有力な選択肢になります。変更する範囲を抑え、必要な機能から追加できます。
一方、古いテーブルの項目をそのまま公開するだけでは、既存の複雑さが新しいシステムにも持ち込まれます。API化を将来の変更に生かすには、業務の意味と責任の境界を設計する必要があります。
公開する単位を、業務上の操作から考える
たとえば「注文テーブルを更新する」というAPIだけを用意すると、利用側が注文の状態、明細との関係、変更可能な条件を知る必要があります。連携先が増えるほど、同じ業務判断が複数の場所に散らばる可能性があります。
「注文を受け付ける」「注文を取り消す」「出荷状況を照会する」のように、利用側が実行したい操作から考えると、既存側に残す判断が明確になります。すべてを大きなAPIにまとめる必要はありませんが、整合性を保つために一体で判断すべき処理は、境界を分けすぎないことが大切です。
仮の例として、注文の取消を考えます。新しい画面から取消フラグだけを書き換えると、在庫引当の解除や後続への通知が実行されないかもしれません。既存の業務機能を経由できるなら、その処理をAPIから呼び出す方法を検討します。直接DBを更新する場合は、どのチェックや更新が迂回されるのかを把握し、整合性を維持する責任を明確にします。
変換するのは、形式と業務上の意味
既存システムの数値コードを文字列へ変えるだけでは、十分な連携設計にならないことがあります。旧側の「完了」が入力完了を表し、新側では出荷完了を表すなら、同じ名称でつなぐと誤解を生みます。
Microsoftが紹介しているAnti-Corruption Layerは、意味やモデルが異なるシステムの間に変換層を置き、一方の内部事情によって他方の設計が過度に制約されるのを防ぐパターンです。
Microsoft Learn：Anti-Corruption Layer：https://learn.microsoft.com/en-us/azure/architecture/patterns/anti-corruption-layer
この考え方を使う場合も、変換層にすべての業務判断を集めると、新たな複雑さが生まれます。コード、単位、状態の対応づけをどこで行い、承認や在庫の判断をどのシステムが担うのかを決めます。変換層にも運用と保守の担当者が必要です。また、変換層で増える処理時間も含めて確認することが欠かせません。
APIの契約で決めること | 具体的な確認内容 |
操作の意味 | 受付と処理完了を区別できるか |
入出力 | 必須項目、単位、時刻、状態コードの意味 |
更新責任 | どのシステムが正しい状態を保持するか |
権限 | 誰が、どの部門・データに、何を実行できるか |
失敗時の扱い | 未実行、実行失敗、結果不明をどう識別するか |
変更の扱い | 利用側への通知、互換性、旧版の終了条件 |
認証済みだからといって、すべてのデータにアクセスしてよいわけではありません。ユーザーや連携元の識別と、対象業務・対象データに対する権限確認を分けて設計します。共有アカウントだけに依存すると、実際の操作者を追えなくなる場合もあります。
タイムアウト後の再送で、二重処理を起こさない
APIがタイムアウトしたとき、呼び出し元からは失敗に見えても、既存システム側では処理が完了していることがあります。そのまま再送すると、注文や出荷指示が二重に作られる可能性があります。
対策の一つが、同じ要求を繰り返し受けても効果が重複しないようにする冪等性の設計です。AWS Builders' Libraryでは、呼び出し元が指定する要求IDを使って再送を識別する方法が説明されています。
AWS：冪等性を備えたAPIによる安全な再試行(https://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/)
設計時には、要求IDの有効範囲と保存期間、同じIDで内容が変わったときの扱い、同時に同じ要求が到着した場合の制御を決めます。IDの保存だけが成功し、業務更新が失敗する状態も避ける必要があります。旧側の更新と受付記録を一つのトランザクションで確定できない場合は、再照会や照合によって結果を確定する方法を含めて検討します。
APIの入口でIDを確認するだけでは、その先で動く旧処理まで二重実行を防げるとは限りません。どこまでを一回の処理として保護できるかを明らかにし、通信が切れた直後や再起動時も試験します。
同期と非同期を、利用者が必要とする結果で選ぶ
利用者がその場で確定結果を必要とする処理には、同期呼び出しが分かりやすい場合があります。ただし、複数のシステムを順に呼び出すと、待ち時間や一か所の停止の影響が利用者にまで及びます。
時間のかかる処理や後続への通知では、要求を受け付けて後から処理する非同期方式が候補になります。この場合は、受付番号、処理中、完了、失敗といった状態を利用者が確認できることが重要です。「受け付けた」という応答が業務の完了と誤解されないように表示します。
DB更新とメッセージ送信を別々に実行すると、一方だけが成功する可能性があります。Transactional Outboxは、業務更新と送信用の記録を同じDBトランザクションに保存し、その後に送信する方法です。それでも送信が重複する可能性は残るため、受信側で重複を防ぐ処理も必要です。
AWS：Transactional Outboxパターン(https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/transactional-outbox.html)
この方式を既存環境に適用できるかどうかは、トランザクションの境界や改修可能な範囲によります。導入すればシステム全体が一括で確定されるわけではありません。途中で止まった処理をどう回復し、必要な場合にどの業務操作で取り消すかも設計します。
連携を増やす前に、監視と廃止条件を決める
障害時には、要求IDや相関IDで入口から既存処理までを追跡できると、調査を進めやすくなります。成功率や応答時間に加え、未処理の滞留、最も古い待機時間、再送回数、結果不明の要求を確認できるようにします。障害を受け付ける窓口と、旧側・新側それぞれの対応担当も決めます。
段階的な刷新では、同じ業務データを新旧の双方が自由に更新する期間を作らないよう、更新責任を定めます。また、変換層が一時的な橋渡しなのか、長期的な連携機能なのかも明確にします。一時的な仕組みなら、利用元の移行、未処理データの解消、旧APIへのアクセス停止など、撤去できる条件を計画に含めます。
株式会社Managetechは、既存資産をAPIで活用する際、呼び出せることに加えて、変更と運用の責任を分けられることを重視します。最初の対象には、入出力、業務上の完了、失敗時の扱いを説明できる機能を選びます。そこで得た設計と検証結果を基に、連携範囲を広げる進め方を提案します。
コメント