ルートやレスポンスフィールド、APIバージョンの削除は、範囲の限られた変更に見えるかもしれません。しかし、アプリケーション、パートナー、自動化プロセスがそのインターフェースに依存していれば、サービスの保守チームから離れた場所で影響が表面化することがあります。連携を壊さずにAPIバージョンを廃止する方法を判断するには、誰が利用しているかを把握し、検証可能な代替手段を用意したうえで、カレンダー上の日付だけでなく証拠に基づいて廃止を進める必要があります。
まず、公開インターフェースと内部実装を区別します。観測可能な契約を変えずにPHPクラスをリファクタリングするのは、通常、内部変更です。JSONレスポンスの変更、パラメーターの受け付け停止、ルートの動作変更は利用者に影響するため、互換性の評価が必要です。また、技術的なデプロイが廃止と同義とは限りません。新バージョンがデプロイ済みでも、全利用者にリリースまたは有効化されているとは限りません。
廃止を告知する前に利用者を洗い出す
まず、複数の情報源から手がかりを集めます。ドキュメントやAPI契約からは本来使われるべき内容が分かり、トラフィックログからは実際に観測された内容が分かります。認証情報、キー、アカウントは、呼び出しを組織に関連付けるのに役立ちます。通常、どれか一つの情報源だけでは不十分です。複数の利用者が認証情報を共有していたり、正しく識別されなかったりする可能性があります。
- 仕様、使用例、SDK、統合テスト、パートナー向けドキュメントを確認します。
- ルート、バージョン、メソッド、利用者の識別情報、利用期間ごとにリクエストを分析します。トラフィックだけでは、クライアントがレスポンスのどのフィールドを使用しているか分かりません。それを測定するには、専用の計測か利用者から提供される情報が必要です。
- 定期実行ジョブや、断続的にしかトラフィックがないシステムを特定します。今週リクエストがないからといって、連携が放棄されたとは限りません。
- 既知の各利用者について、社内の担当者を割り当て、可能であれば外部の連絡先も特定します。
- この分析にログを使う前に、ログの保存期間と機密データの有無を確認します。
APIで利用者を識別できない場合、その不足はリスクの兆候であると同時に、改善の機会でもあります。適切な識別情報とメトリクスを導入すれば、今後の移行が容易になります。リクエスト本文全体や不要な個人データの記録は避けてください。通常、利用状況の測定には、アクセス制御されたリクエストメタデータの集計値で十分です。
実際の契約に基づいて変更を分類する
すべての変更に同じ移行が必要なわけではありません。既存フィールドを変えずに任意のフィールドを追加するような追加的な変更は、通常は互換性があります。ただし、厳密な検証を行うクライアントは、未知のフィールドを含むレスポンスを拒否することがあります。条件付きで互換性のある変更では、利用者に設定の調整や代替手段の利用開始を求める場合があります。既存の前提を変える変更は、たとえ対象が一つのルートやプロパティだけでも、互換性のない変更として扱う必要があります。
リクエストとレスポンスの両方を評価します。受け付けていたパラメーターの削除、検証の厳格化、デフォルト値の変更、ステータスコードの変更、フィールドの削除はいずれもクライアントを壊す可能性があります。また、型だけでなく意味も確認してください。型は文字列のままでも、表す内容が変われば機能上の互換性が失われることがあります。
現在の契約、新しい動作、影響を受ける利用者、提案する代替手段を文書化します。分類に確信が持てない場合は、代表的なクライアントでテストするか、証拠がそろうまで互換性を維持してください。あらゆる変更にバージョンを付けると複雑さが増すことがあります。新しいバージョンを本当に互換性のない変更に限ることで、バージョニング方式の意味を保ちやすくなります。
観測・周知できる移行を計画する
次のような手順を踏むと、想定外の事態を減らし、必要に応じて方針を修正できます。
- 告知する: 廃止するインターフェース、その理由、代替手段、影響を受ける可能性のある利用者を説明します。利用者が実際に確認するチャネルで情報を公開します。
- 代替手段を用意する: ルート、パラメーター、使用例、動作の違いを文書化します。移行とテストに使える手順を維持します。
- 移行状況を測定する: 利用者ごとに旧・新インターフェースの使用状況を観測します。何を移行完了とみなすか、どの例外を確認するかを事前に定めます。
- 制御しながら廃止する: 残存利用がない、または残存利用の理由が説明されており、テストに合格し、インシデント対応手順が整っていることを確認してからアクセスを終了します。
告知には、対象のルートまたはバージョン、予定日、曖昧さが生じる可能性がある場合はタイムゾーン、影響、支援を求める方法を明記します。日程には、利用者側の計画とテストのサイクルに見合った猶予を設ける必要があります。一律の期限はありません。移行が完了していない場合、重要な連携を中断してまで予定を守るより、日程を見直すほうが安全なことがあります。
環境が許す場合は、レスポンスやヘッダーに警告を含めることで告知を補完でき、ドキュメントを確認しないクライアントの検出にも役立ちます。ただし、これを唯一の周知手段にしないでください。こうしたシグナルを確認しない利用者もいます。たとえば、まずテスト用の利用者や合意済みのグループに変更を限定する段階的な適用は、廃止の告知とは異なります。両者の目的はそれぞれ異なります。
互換性をテストし、メトリクスで検証する
変更前に、契約を自動テストに落とし込みます。コンシューマーテストでは、各クライアントが宣言する前提を検証します。プロバイダーテストでは、APIが引き続きその契約を満たしているかを確認します。認証、検証、エラー、ページネーションや上限に関する重要なケースの統合テストも追加します。PHPでは、こうしたチェックをアプリケーションのテストとともにCIで実行できますが、実際のトラフィックの観測に代わるものではありません。
バージョン間の比較に使えるベースラインとメトリクスを定義します。たとえば、利用者・ルート別のリクエスト数、エラー、新しい代替手段へのトラフィックの割合です。クライアントがレスポンスのどのフィールドを利用しているかを知るには、専用の計測か利用者から提供されるデータを使います。記録されたリクエストだけから推測することはできません。既知の利用サイクルをカバーする期間を設定します。データは背景を踏まえて解釈してください。あるシーズンにリクエストがない利用者でも、月次締め、更新、年次タスクで再び使われることがあります。
代表的な環境で廃止手順もリハーサルします。旧インターフェースへのリクエストでアラートが発報され、チームがそのリクエストを識別情報と担当者に結び付けられることを確認します。大量のログを手作業で調べることに測定を依存させないでください。
残存利用に対応し、ロールバックに備える
クライアントが引き続きそのインターフェースを使用している場合、まずトラフィックが正当なものか、発生元は誰か、どの処理を行っているかを特定します。利用者が告知を確認しなかったと結論づける前に、認証情報の共有、ソフトウェアのバージョン、廃止手順を確認します。具体的な証拠と移行手順を担当者に伝え、他の利用者のデータは公開しないでください。
選択肢には、移行期間の一時延長、範囲を限定した例外の合意、アーキテクチャが許せばグループ単位での廃止があります。すでに中断が発生している場合は、安全であれば以前の動作を一時的に復元するか、利用者を互換性のある代替手段にルーティングすることを検討します。ロールバックによって脆弱性を復活させたり、セキュリティ上の義務に反したりしてはいけません。誰が決定するのか、どの条件でロールバックするのか、どのように周知するのかを記録します。
廃止完了時のチェックリスト
- 既知の利用者それぞれに担当者、状況、連絡手段が設定されている。
- 契約に照らして変更が分類され、代替手段がテスト・文書化されている。
- 告知、日程、例外が適切なチャネルで伝えられている。
- メトリクスが関連する利用期間をカバーし、残存トラフィックの理由が説明されている。
- プロバイダーとコンシューマーのテスト、アラート、ロールバック手順が検証されている。
- 廃止後にエラーとリクエストを確認し、仕様、SDK、使用例、ドキュメントを更新している。
サービスが古い契約を公開しなくなり、影響を受ける利用者に既知の移行先があり、計測と観測範囲の既知の制約を踏まえたうえで、代表的な期間に残存利用が検出されなければ、廃止は完了です。ログやメトリクスは証拠になりますが、未知の利用者や断続的な利用が存在しないことを証明するものではありません。この基準により、廃止は新バージョンが利用可能になったという事実だけに賭けるのではなく、制御された運用上の判断になります。
