連携が正常に応答していても、データを誤って処理していることがあります。プロバイダーがフィールドの意味を変更したり、企業向けプラットフォームが2つのAPIバージョンを提供したり、クライアントが異なる認証設定を維持していたりするためです。ソフトウェア連携の互換性マトリクスを使えば、アプリケーションがサポートする組み合わせ、検証済みの組み合わせ、それぞれの制約を記録できます。
これは、存在するすべての製品を並べた一覧でも、あらゆる環境で動作するという保証でもありません。何をカバーし、逸脱をどう検知し、依存先に変更があったとき誰が対応するかを判断するためのツールです。PHPアプリケーションでは、技術的な依存関係の一覧を自動テスト、監視、変更手順と結び付けられます。
連携における互換性とは
互換性はAPIのバージョンだけにとどまりません。少なくとも次の5つの側面に分けて考えるとよいでしょう。
- 形式：リクエストとレスポンスの構造、コンテンツタイプ、文字エンコーディング、シリアライズ方式。
- フィールド：名前、型、必須かどうか、null値、許容値、検証ルール。
- 意味：各データが何を表し、どの単位やタイムゾーンで解釈されるか。フィールドが存在していても、意味が変わっている場合があります。
- アクセス：認証方式、権限、認証情報の有効期限、必要なスコープ。
- 挙動：エラーコード、リクエスト制限、イベントの順序、再試行、冪等性。
マトリクスでは、追加的な変更と非互換な変更を区別する必要があります。任意フィールドの追加は、未知のフィールドを無視するコンシューマーには影響しないことがあります。一方、必須フィールドの名称変更は連携を壊す可能性があります。評価は、実際の連携契約とクライアントコードの実装に左右されます。
依存先と重要な組み合わせを洗い出す
まず、外部システムごとに、API、Webhook、インポートファイル、キュー、ライブラリ、コネクターなどの接点を列挙します。保守担当者、利用するPHPアプリケーション、やり取りするデータ、その依存先に依存する業務処理を記録してください。リージョン、認証方式、日付形式など、挙動を変える可能性のある環境や設定も含めます。
次に、確認できているバリエーションと公式にサポートされているバリエーションを特定します。APIバージョン、プラットフォームバージョン、ペイロードスキーマ、アクセス設定などです。理論上の組み合わせがすべて重要だと決めつけないでください。具体的な指標に基づいて優先順位を付けます。
- 影響を受けるトラフィック量や業務処理数。
- 利用中の顧客、リージョン、インストール環境での使用状況。
- 障害の影響と、処理を復旧または再実行できるかどうか。
- 変更や障害の履歴、バージョン間で既知の差異。
- テスト環境や代表性のあるデータを利用できるかどうか。
組み合わせが多い場合、すべてをテストする必要はありません。リスクに基づいてカバレッジを定めます。利用頻度の高いバージョン、最新バージョン、サポート境界、認証方式やスキーマが異なる組み合わせを優先します。未テストの組み合わせも記録してください。記載がないことを、互換性が確認済みだと解釈してはいけません。
実用的で対応につながるマトリクスを作る
1行には単なるプロバイダー名ではなく、検証可能なシナリオを記載します。システム、バージョン、操作、形式、認証、サポート状況、検証レベル、制約、担当者、レビュー日などを含めます。その状態の根拠となる自動テスト、fixture、検証記録への参照も追加します。
状態は明確に定義します。たとえば、「サポート対象・テスト済み」「文書化された制限付きでサポート」「検証待ち」「サポート対象外」などです。プロバイダーが表明する互換性と、チームが検証した互換性を区別してください。第三者の公式見解では互換性があるバージョンでも、自社アプリケーションでテストされているとは限りません。
最小・最大バージョン、対象操作、未対応の挙動、連携を有効化するための条件など、境界も定義します。マトリクスを更新し、例外を承認する担当者を割り当ててください。担当が明確でなければ、テストが実行され続けても文書は古くなりがちです。
優先シナリオをテストに落とし込む
テストでは、リクエストがHTTP 200を返すかだけでなく、契約と重要な結果を確認する必要があります。優先シナリオごとに、構造、型、必須フィールド、意味上のルール、想定されるエラーへの応答を検証します。該当する場合は、ページネーション、制限、重複、再試行、認証の有効期限切れも含めます。
PHPアプリケーションでは、バージョン管理されたfixtureを使って、ユニットテストでアダプターやマッパーを検証できます。契約テストでは、リクエストとレスポンスが想定された取り決めに沿っているかを確認します。利用可能であれば、統合テストでプロバイダーの管理された環境との通信を検証します。各レベルが答える問いは異なります。fixtureだけではリモートサービスが稼働し続けていることを証明できず、サービスに対するテストも、データ変換の決定論的なケースの代わりにはなりません。
必要に応じて、代表的なfixtureを匿名化して保存します。トークン、不要な個人データ、機密情報を含めないでください。プロバイダーがスキーマを頻繁に変更する場合、自動的な契約比較で差異を検出できます。その差異が無害か、非互換か、業務上重要かは、人がレビューして判断する必要があります。
非互換な変更に後手で対応しない
プロバイダーからの通知、ドキュメントの新バージョン、予期しないレスポンス、検証エラー、エンドポイントやバージョンごとの障害指標など、変更を検知するためのシグナルを定めます。障害を特定のシナリオと関連付けられるよう、認証情報や機密データを露出させずに、観測したバージョンやバリエーションをログに記録します。
差異が見つかったら、コードを変更する前に分類します。追加フィールドを許容すれば済む場合もあれば、型の変更には明示的な変換が必要なこともあります。意味の変更にはプロダクト上の判断が必要かもしれません。対応はクライアントやアダプターなど明確な境界に閉じ込め、プロバイダー固有の事情がアプリケーション全体に広がらないようにします。
更新をすぐに有効化できない場合は、新バージョンのテスト、段階的なデプロイ、エラーの監視、ロールバック手順を含む移行計画を定めます。コードをデプロイすることと、新しいルートや公開対象をすべてのユーザーに有効化することは同じではありません。アーキテクチャが許す場合、有効化は段階的に進められます。処理中の操作では、すでに送信されたメッセージとの互換性を保ち、再試行時に非冪等な操作を重複実行しないようにします。
処理を中断せずにバリエーションを廃止する
あるバージョンのサポートを終了するには、プロバイダーのサポート終了、残存利用、テスト維持のコスト、セキュリティリスク、挙動を保証できないことなど、明確な基準が必要です。廃止前に利用状況を測定し、影響を受けるコンシューマーを特定します。期限を合意し、変更を周知して移行先を提示すれば、予期しない影響を減らせます。
バリエーションの廃止と、データや未処理プロセスの即時削除を混同しないでください。キュー、同期処理、スケジュール済みジョブがある場合、安全に完了、再試行、移行できることを確認します。期限後の拒否は、明確に記録し、観測可能にしてください。古い連携が気付かれないまま劣化し、データ破損につながる状態を許してはいけません。
依存先を変更するときのチェックリスト
- 影響を受けるバージョン、形式、認証、操作について、一覧を更新したか。
- 契約を比較し、型と意味の変更を評価したか。
- 優先する組み合わせとエラーケースをカバーするfixtureとテストがあるか。
- 権限、シークレット、個人データ、リクエスト制限を確認したか。
- 担当者、有効化基準、監視、ロールバックが定義されているか。
- バリエーション廃止前に移行が必要な顧客やプロセスを特定したか。
- 何をテストし、何が未対応で、いつ再レビューすべきかをマトリクスに反映したか。
ソフトウェア連携の互換性マトリクスは、何をどの証拠に基づいて、どの制約のもとで、いつまでサポートするかという検証可能な判断に役立つとき、価値を発揮します。テストや変更プロセスと一緒に管理すれば、価値につながらない網羅性を追い求めずに、予期せぬ事態を減らせます。
