Web APIの廃止：ベストプラクティス？

最終的に、パブリックWeb APIの一部を減価償却する必要があります。しかし、私はそれを行うための最良の方法が何であるかについて混乱しています。大規模なサードパーティアプリベースがある場合、ほとんどすべてのアプリが一晩で失敗するため、古いバージョンのAPIをヤンクするだけでは間違った方法のように思えます。ただし、古くなったWeb APIを永久に使用できる状態に維持することはできません。

古いWeb APIを廃止するためのベストプラクティスは何ですか？

元のポスターはすでに効果的に機能しているように聞こえますが、非公式にAPI（「古いAPI」と呼ばれるもの）は非推奨になりました。ただし、アナウンスされ、APIが非推奨になったことをユーザーに通知するまで、正式には非推奨ではありません。

非推奨のAPIは、暫定的な非アクティブなコード段階です。最後の儀式です。これは、採用者/消費者が新しいAPI用にアプリを再構成し、APIに安らぎを与えて別れを告げる期間です。一部のAPIは他のAPIよりも長く残る場合がありますが、現時点では時間が長くないことがわかります。

削除されたAPIはコード葬儀です。それ以上のことはできませんが、適切に処分され、適切に記念されます。

多くのAPIおよびサービス開発者は、最後の儀式を行うのではなく、コード葬儀を選択します。ただし、それはややリスクがあると思います。API /サービスが最初に採用されたときまたは更新を通じて行われたときに何らかのサービスまたはサポートの約束があった場合、葬儀を行う前にそのコミットメントを妥当な期間尊重することができます。

非サービスライブラリの場合、期間に関係なく、メジャーリリースバージョンの1つはおそらく、後方互換性が保証された許容できる公正な期間よりも長いと思います。それ以上は、その期間を超えて寿命を延ばすために、ユーザーによる影響とロビー活動に依存します。また、取り返しのつかないサードパーティの依存関係が不明確であり、特定のプラットフォームの特定のバージョンに関連付けられていることに起因する異議がある場合は、驚かないでください。

サービスについては、誰がどのようにサービスを消費できるか、およびプロジェクトの消費からプロジェクトの消費までの対応する開発サイクルの違いのために、6か月または1年の期間を検討する必要があると思われます-サービスを消費する可能性のある多くのプロジェクトは、まだ大きな初期設計であり、1年以上のリリースサイクルをスケジュールする可能性があります。外部からの開発者の意見のほとんどは、スケジュールが長い人があなたのサイクルタイムを満たす責任があり、長いサイクルを消費するプロジェクトはより速いリリースサイクルを採用すべきだと示唆しています。しかし、最終的に削除日はユーザーと交渉する必要があるものです。

非推奨の良いが完全ではない戦略は、非推奨を通知するときに、削除する意図の時間枠を強調し、問題のAPIセクションの調査形式でコメントまたは異議のリクエストをすることです。サービスが[半]匿名アクセスで動作しているためにユーザーの連絡先リストがない場合は、頻繁にアクティブなユーザーのログを調べて、ホストまたはドメイン管理者に通知を送信し、必要に応じて転送することを検討してください。

私が使用しているWeb APIのほとんど（Google、Yahoo！、Microsoftなど）には「日没」期間があります。開発者は、事前にアップグレードするための十分な時間を与えるために、減価される予定の機能について、妥当な時間内（たとえば3〜6か月）に通知されます。

利用規約やその他のドキュメントに日没期間の詳細を追加して、その仕組みを人々に知ってもらうことができます。これは、誰かがあなたのAPIを使用することに決めたとき、彼らがどのスケジュールを扱う必要があるかを知ることを意味します。たとえば、1年に1回システムをアップグレードする必要があることを通知し、4か月前にアップグレードを通知することができます。

また、バージョン番号を使用することをお勧めします。たとえば、「バージョン3は間もなく減価するので、コードがバージョン4で動作することを確認してください」などと言うことができます。 4その後、彼らは日没の準備ができています。

プロセス角度からの追加情報：

• すべての利害関係者と通信する：他のチームとAPI消費者に、APIを非推奨にする理由、戦略、計画とスケジュールの詳細、バージョン管理の意味、代替案について明確かつ簡潔なコミュニケーションを提供し、それに応じてHTTPを設定します。

• 計画とスケジュール：計画には、重要なマイルストーンと廃止予定の目標日が必要です。消費者に同じことを求め、消費者がコールを廃止する日付を提供する必要があります。定期的な会議を開催して、プロセスを監視し、消費者をサポートします。

• バージョン管理と代替案の提供：バージョン管理は、メジャーリリースでの重大な変更を示し、APIの廃止戦略を立てるのに役立ちます。

• Sunset HTTP応答ヘッダーの設定：HTTPヘッダーは警告の技術的な役割を果たします。APIコンシューマーは、このタイプのコードを監視して、APIが非推奨になる時期を理解する必要があります。

• 前後の監視：消費者を監視し、一定期間が過ぎてもAPIを使用している消費者にアラートを送信します。

ユーザーがコードを更新できるように、既存の回答に加えて、何かを削除するときにドロップイン置換または移行計画を提供する必要があります。

代替手段を提供せずに機能を削除しないようにしてください-これにより、ユーザーの一部が不満に思うでしょう。