お題とスコープ
プロバイダーは移行期間の後に /v1/items を削除したいと考えていますが、クライアントは異なるチームによって所有されており、一部は休止状態です。プロバイダーはクライアントの識別情報ごとにリクエストを観測でき、/v2/items を並行して実行できると仮定します。計画では、非推奨の告知と削除日を区別し、安全なフォールバックを維持し、ヘッダー単体でクライアントが移行すると決めつけないようにする必要があります。
面接官が見ているポイント
- プロトコルシグナル、ドキュメント、クライアントインベントリ、および強制適用の分離。
- 追加的（アディティブ）な互換性と、測定可能な移行ゲートの設計。
- 未知のクライアント、長期間運用されている連携、および緊急ロールバックへの対応。
- 標準を超えた独自セマンティクスを作ることなくステータスコードとヘッダーを選択できるか。
確認すべき質問
クライアントが安定した識別情報を送信しているか、/v2 は追加的な変更が可能か、最低サポート期間、契約上の通知要件、および削除前に古いエンドポイントを読み取り専用にできるかを確認します。識別情報がない場合、移行のエビデンスは推測されたユーザーエージェントではなく、認証情報、ネットワークメタデータ、または明示的な登録から得る必要があります。
30秒で答える要約
まず呼び出し元のインベントリを作成し、バージョン管理された移行ガイドを公開し、/v2 を追加的に提供して、クライアントごとのトラフィックとエラーパリティを測定します。/v1 には標準化された Deprecation シグナルと Sunset 日付を付与し、既知のオーナー向けにダッシュボードと直接通知を提供します。規定の期間中は古いパスを維持し、エビデンスゲートを通過した後にのみ強制適用を実施して、移行リンクを含むドキュメント化された終端レスポンスを返します。機能フラグと可逆的なルーティングにより、重要なクライアントで障害が発生した場合のロールバックを担保します。
ステップごとの詳細解説
1. 互換性とエビデンスの確立
フィールドレベルの差異、デフォルトの挙動、ページネーション、エラー、認証の変更を定義します。両方のバージョンに対してコントラクトテストを実行し、代表的なレスポンスを比較します。メトリクスにはクライアント、バージョン、エンドポイント、ステータス、移行状態をタグ付けします。低トラフィックのクライアントがビジネス上極めて重要である可能性があるため、集計トラフィックのみを使用して判断してはいけません。
2. 非推奨シグナルを正確に送信する
Deprecation レスポンスヘッダーはリソースが非推奨であることを伝え、Sunset ヘッダーはそれ以降利用できなくなる予定日を伝えます。これらはシグナルであり、すべてのクライアントが理解することを保証するものではありません。ドキュメントやオーナーへの通知で日付を繰り返し周知し、レスポンスボディまたはAPIコントラクトで定義されたリンク関係に安定した移行リファレンスを含めます。
3. 段階的な移行と強制適用
まずは警告とダッシュボードから開始し、期日に間に合わないクライアントには明示的な例外申請を義務付けます。デフォルトを切り替える前に、シャドー比較やオプトイン方式のトラフィックを提供します。強制適用ゲートでは、廃止しても安全な古い操作のみを拒否し、機械可読なエラーを返し、サポート窓口への導線を維持します。リスクの度合いが異なる場合、読み取り専用の互換性はミューテーション（更新系）の互換性よりも長く維持できます。
4. ロールバックとガバナンスの実効性を維持する
サンセット日、オーナー、例外理由、および承認内容を変更履歴レコードに記録します。移行後のエラー差分や未知のクライアントからのリクエストに対してアラートを設定します。古いパスを機能フラグ経由でルーティングし、ロールバックがコードの再デプロイではなく設定変更で済むようにします。削除後も、秘密情報を公開することなく失敗理由を説明できるよう、テレメトリとトゥームストーン（tombstone）レスポンスを十分な期間保持します。
優れた回答例
10,000の呼び出し元をインベントリ化し、/v1 から /v2 への正確なコントラクト差異を定義します。両バージョンを並行して実行し、クライアントごとのメトリクス収集とコントラクトテストを実施します。/v1 のレスポンスには Deprecation および Sunset シグナルを含め、ドキュメントとオーナー通知で期日と移行手順を繰り返し周知します。プロバイダーは、警告、オプトイン、v2デフォルト化、強制適用の各段階を進め、明示的な例外対応と機械可読な終端エラーを用意します。機能フラグによってロールバックを可能な状態に保ち、サンセットゲートは集計トラフィックの割合ではなく、クライアントレベルのエビデンスに基づいて判断します。
よくある落とし穴
- ヘッダーが移行を行ってくれると思い込む → 多くのクライアントはヘッダーを無視する → 標準シグナルをオーナーの特定および移行ガイドと組み合わせる。
- インベントリなしで日付を設定する → 休止中だが重要なクライアントが予期せず停止する → クライアントの識別と例外レビューを必須化する。
- 集計エラー率のみを比較する → 単一テナントの障害が平均の中に埋もれる → クライアントごとのパリティとボリュームを監視する。
/v2のリリース直後に削除する → クライアントに互換性を確認する余地がない → まず並行運用やオプトイン段階を設ける。- ロールバックを再デプロイ頼みにする → 障害時の復旧が遅れる → バージョンを可逆的なフラグの背後にルーティングする。
- サンセット時にドキュメント化されていない404を返す → 自動処理において削除とタイポの区別がつかない → 安定した終端エラーと移行リファレンスを公開する。
フォローアップ質問と回答
クライアントが識別用ヘッダーを一切送信しない場合、移行ゲートはどうすべきですか？
プロバイダーがすでに利用可能な認証情報、アカウント、ネットワーク、または登録時の識別情報を使用します。どれも信頼できない場合は、エンドポイントの提供期間をより長く維持し、強制適用前に明示的な登録を義務付けます。
Sunset 日付を延期することは可能ですか？
変更レコード、ドキュメント、ヘッダー、およびオーナーへの通知が同時に更新されるのであれば可能です。日付はガバナンス上のコミットメントとして扱い、古いパスに依然として依存しているクライアントに対してアラートを発報します。
/v2 は正常に動作するものの、特定のクライアントで処理速度が低下した場合はどうしますか？
そのクライアントのレイテンシとエラーバジェットを個別に比較し、最適化を行うか期間限定の例外を認めます。問題がシステム全体のものであるという証拠がない限り、すべての利用者を対象としたサンセット期間を一律に延長してはいけません。
ミューテーション（更新系）エンドポイントを安全に廃止するにはどうすればよいですか？
エビデンスゲートの後に新規の書き込みを停止し、可能な場合は読み取りアクセスを維持し、リトライに対しては決定論的な終端エラーを返します。削除前に、ダウンストリームのキューや監査ログが古いミューテーションに依存していないことを確認します。