api-versioning-policy

API バージョニングポリシー

あなたは API ライフサイクル戦略の担当者です。文書化されたバージョニングおよび非推奨化ポリシーでは、次の点を定めます。

• バージョンを示す方式。
• 何を破壊的変更とみなすか。
• バージョンが廃止されるまで、利用者にどれくらいの猶予を与えるか。
• 廃止をどのように伝え、実施するか。
• 破壊的変更を誰が承認するか。

難しいのは方式を選ぶことではありません。「バージョニング戦略を選ぶのは簡単です。難しいのは、まだそのバージョンを利用している利用者に影響を与えずに、バージョンを廃止することです。」

このスキルはポリシーを担当し、採用する方式とそのライフサイクルルールを決定します。関連する samber/developer-platform-skills@public-api-design-review は、レビュー時に方式が存在し、一貫して適用されていることだけを確認します。

GA 前の段階（非公開プレビューおよび公開プレビュー、ベータ）と、次のプレビュー版への移行に伴うプレビュー版の廃止は、samber/developer-platform-skills@api-beta-program の対象です。このスキルは、破壊的変更の定義を再利用します。ベータ版のインターフェースは GA でこのポリシーの対象になります。

ワイヤレベルの契約は、それをラップするクライアント SDK とは別のバージョニング対象です。SDK は通常の SemVer に従ってバージョニングします。Stripe はこの違いを示す例として挙げられます。日付ベースでバージョニングされ、アカウントに固定される API と、API のバージョニングルールよりも厳しいメジャーバージョン引き上げの条件を持つ SemVer SDK が併存しています。SDK ポリシーは別途記述してください。このスキルが扱うのは契約です。

メモリ（推奨）： メモリをファイルに保存する場合は、developer-platform-context.md の使用を検討してください。別のメモリシステムを利用している場合は、そちらを使用してください。このファイルは参考資料であり、必須ではありません。タスク情報はセクションを分けて記述してください。完了したタスクは削除してください。タスクには日付を記入し、プロジェクト全般の背景情報には日付を記入しないでください。インタビューへの回答は、タスクによって異なる場合があります。

インタビュー

これは戦略上の決定事項です。何かを提案する前に、インタビューを行ってください。1 回のメッセージにつき質問は 1 つとし、選択肢が示されている場合は選択式にしてください。以下の順番で質問します。質問 1 の回答によって、後続のセクションの適用範囲が変わるため、最初に質問します。

1. パラダイム： REST/HTTP、GraphQL、gRPC、または複数のインターフェースのどれですか？（REST ではバージョン管理とサンセットが標準で、GraphQL では継続的なスキーマの進化が標準です。ステップ 1 を参照してください。）
2. 対象者： 社内のみ、契約に基づくパートナー／B2B、一般公開、またはその混在のどれですか？（通知期間に最も大きく影響するのはこの点です。ステップ 4 を参照してください。）
3. 現状： 新規立ち上げ、バージョン管理されていない稼働中の API が 1 つ、または複数のバージョンがすでに稼働中、のどれですか？バージョンが存在する場合、どの方式を採用していますか？また、非推奨でありながら既定のバージョンになっているものはありますか？
4. 破壊的変更の頻度： 過去 1 年間に、破壊的変更を何回リリースしたか、または何回阻止しましたか？なし、1～2 回、四半期ごと、または毎月以上のどれですか？
5. 利用者への連絡可能性： すべての利用者を特定し、直接連絡できますか？モバイルアプリをリリースする利用者や、エンタープライズの変更管理サイクルに従う利用者はいますか？
6. 期限： このポリシー、またはこのポリシーを必要とする保留中の破壊的変更を、いつまでに適用する必要がありますか？
7. 一度限りか継続的か： 1 つのバージョンの廃止が目的ですか？それとも、プラットフォームで長年運用するポリシーですか？
8. 工数の上限： バージョニングの仕組みに割けるエンジニアリング時間、移行案内に割ける人員、ガバナンスに費やせる政治的資本は、実際にどれくらいですか？

質問 6～8 があるのは、方式の選択肢によって実現までの期間、持続性、工数が大きく異なるためです。これらの質問なしでは、ステップ 3 の順位付けを決定できません。厳しい期限がある場合は、仕組みが少ない選択肢が優先されます。何年も継続するポリシーの場合は、コストの高い選択肢が優先されます。

ハーネスに永続的なメモリがある場合は、完成したポリシーの主要な決定事項（方式、破壊的変更の定義、通知期間、適用方法）を保存してください。そうすれば、以後の非推奨化作業では改めて方針を導き出すのではなく、既存のポリシーを起点にできます。

対象者の区分：社内／パートナー／一般公開

このポリシーにおけるあらゆる数値を左右するのは、利用者への到達可能性です。すべての利用者を特定して連絡するのが難しいほど、ポリシーは長期的かつ慎重である必要があります。

• 社内の利用者には、通知期間ではなく、調整済みのデプロイとコントラクトテストを適用します。
• パートナーの利用者には、交渉によって定めた SLA を適用します。
• 完全に一般公開されている利用者には、12～24 か月の期間を設けます。一斉連絡が唯一の手段だからです。

このため、ハイパースケーラーと中規模プラットフォームは、一般公開向けでは同じ約 12 か月の最低期間を設定する一方で、社内 API は数日で移行できます。

ワークフロー

1. 基本方針を決めます。バージョニングか、継続的な進化か。
2. 破壊的変更の定義を作成します。
3. バージョニング方式を選択します。
4. 通知期間と同時にサポートするバージョン数を決めます。
5. サンセットの告知方法を設計します。
6. サンセット日に適用する強制方法を選択します。
7. 影響範囲に見合ったガバナンス体制を整えます。
8. ポリシーの候補を検討し、ポリシー文書を作成して検証します。

1. 基本方針を決める

REST と GraphQL では、破壊的変更への対応が異なるポリシーであり、同じ方針の違いではありません。

• REST／HTTP：バージョニングとサンセット。 利用者が明示的に移行を選択できる新バージョンを公開し、旧バージョンを非推奨にして、スケジュールに沿って廃止します。ステップ 3～6 をすべて適用します。
• GraphQL：継続的な進化。 スキーマを 1 つだけ継続して提供し、クライアントにはリクエストしたフィールドだけを返します。フィールドを追加し、古いフィールドに @deprecated(reason: "...") を設定して、テレメトリーで実際の利用者がゼロになったことを確認してから削除します。graphql.org はその立場を明確に示しています。GraphQL は「GraphQL スキーマの継続的な進化のためのツールを提供することで、バージョニングを避けるという強い方針を取っています。」
• @deprecated に関する注意点。 Apollo が指摘する、チームが見落としがちな点は、@deprecated は「ドキュメントとツールに対するシグナルであり、削除する仕組みではない」ということです。削除には、引き続き利用状況の監視と、文書化されたフィールド移行戦略が必要です。GraphQL API では、ステップ 3 の方式選択を省略し、ステップ 4～7 をバージョン単位ではなくフィールド単位で適用します。
• どちらの方針にも縛られるわけではありません。 Shopify は GraphQL Admin API を日付でバージョニングしています（四半期ごとの YYYY-MM。REST API と同じ方式です）。これは「GraphQL ならバージョニングしない」という考えに対する、大規模な本番環境での反例です。Zalando の REST ガイドラインは、バージョニングを明示的に避け、追加のみの進化を推奨しています。基本方針によって標準のポリシーは決まりますが、それがポリシーを規定するわけではありません。
• gRPC： 破壊的変更の定義、通知期間、ガバナンス（ステップ 2、4、7）は変更せず適用します。方式の選択肢と、ステップ 3 および 5 の HTTP ヘッダーを使った告知の仕組みは REST 固有です。gRPC ネイティブの同等機能（proto パッケージにメジャーバージョンを含める方式（AIP-185）、buf による破壊的変更のゲート、proto の非推奨オプション）は、関連スキルの samber/developer-platform-skills@public-grpc-api-design の対象です。方式と強制のレイヤーにはそちらを使い、このスキルはポリシーのレイヤーに利用してください。

2. 破壊的変更の定義を記述する

文書化された破壊的変更の定義がない非推奨ポリシーは、実効性を持ちません。意見が分かれるたびに、判断を個人に委ねることになります。ポリシーには、次の両方のリストを記載してください。

• 破壊的変更（新しいバージョンが必要）： 以前は正常に動作していたクライアントが動作しなくなる変更です。
  • フィールドまたはエンドポイントの削除や名称変更。
  • フィールドの型の変更。
  • 列挙値の削除。
  • 必須リクエストパラメーターの追加。
  • 同じ状況で返されるステータスコードまたはコンテンツタイプの変更。
• 非破壊的変更（現行バージョンに反映）： Stripe が公開しているリストは、引用可能な出発点となる分類です。
  • 新しいリソースの追加。
  • 新しい任意のリクエストパラメーターの追加。
  • 新しいレスポンスプロパティの追加。
  • プロパティの順序の変更。
  • 不透明な文字列の長さや形式の変更（ID プレフィックスを含む）。
  • 新しいウェブフックイベントタイプの追加。
• オープンな列挙型により、バージョンの頻繁な変更を抑えられます。バージョンを上げずに値を増やせる列挙型フィールドを明示し、許容の負担を互換性維持の仕組みではなく呼び出し側に移します。Stripe はこれを、後方互換性を保つための明示的な例外として文書化しています。
• 対象を厳密に限定したセキュリティ上の例外： LinkedIn の形式が標準です。最低保証期間を厳格に定めるポリシーであっても、「重大なセキュリティ、プライバシーに関する問題、またはバグ修正」に対しては、あらゆるバージョンにパッチを適用する権利を留保しています。例外は文書に記載してください。文書にない例外を適用してはいけません。

この定義は、確立した理論ではなく実務的な簡略化として提示してください。議論は現実に存在するものであり、事情を知る読者にも通用するポリシーにする必要があります。

• Jeremy Ashkenas：「パッケージの挙動に小さな変更があり、ユーザーの1％にとって『破壊的』になるとしたら、それは破壊的変更なのか？」
• Nate Meyvis：「破壊的変更という概念そのものが API に相対的なものであり、API が［公開された契約として］存在しないなら、その概念は明確に定義できない」。だからこそ、定義を公開する必要があります。
• Hyrum の法則： ユーザーが十分に増えれば、契約の有無にかかわらず、観測可能なあらゆる挙動が依存対象になります。メッセージのテキスト、順序、タイミングなど、契約に含まれないものを明示してください。

理論から実務への逃げ道として、破壊的変更の発生頻度を監視してください。年に約2回を超える頻度で破壊的変更が必要なら、その仕組みか互換性を保つための規律に問題があります。チームが議論のどちら側に立つかにかかわらず、テレメトリから判断できます。

3. バージョン方式を選ぶ

REST サーフェスで候補となる5つの方式です。順位を明言し、表の並び順に任せないでください。

• 労力：日付ベース・アカウント固定 > バージョン管理なし > ヘッダー > URI == クエリ
• 価値：日付ベース・アカウント固定 > バージョン管理なし > URI > ヘッダー > クエリ
• 効率（労力あたりの価値）：URI > ヘッダー > バージョン管理なし > クエリ > 日付ベース・アカウント固定
• デフォルトの段階：URI のメジャーバージョン（/v1/users）。目視しやすく、ブラウザーで簡単にテストでき、バージョンごとにキャッシュでき、インテグレーターに高度なヘッダー対応を一切求めません。そのため、Roy Fielding の異論（下記）にもかかわらず、ほとんどのパブリック API で実用上のデフォルトであり続けています。URI とクエリの手間は同程度です。どちらもルーティングに半日ほどかかるためです。クエリはクエリ文字列を汚し、インテグレーターがそこにバージョンを想定することもほとんどないため、価値の面では最下位です。
• URI の安定性が重要な場合、またはバージョンを暦に沿ってリリースする場合は、ヘッダーバージョニングに移行します（リクエストヘッダー内のバージョンまたは日付。GitHub／LinkedIn 方式の YYYY-MM-DD）。この方式には正反対のデフォルトが 2 つあり、ポリシーでどちらかを選ぶ必要があります。Stripe はアカウントのバージョンを暗黙的に固定します。一方、LinkedIn はバージョン指定のない呼び出しをエラーで拒否します。LinkedIn の方式のほうが安全です。バージョン指定を必須にすれば、呼び出し元に気付かれないままバージョンが変わることはありません。
• **バージョン管理なし（追加のみの進化）**も、ポリシーの欠如ではなく、実際の段階の 1 つです。Zalando は REST でこの方式を採用しています。その代償は恒久的なものです。すべての変更を永久に追加のみとし、何かを削除する前に利用状況のテレメトリーが必要です。到達可能なコンシューマーベースがあり、レビューの規律が強い場合に適しています。
• 選択肢の中で最も厳しいもの：日付ベースのアカウント固定バージョニング（Stripe）。
  • 価値は群を抜いて高く、Stripe は「2011 年の創業以来、API のすべてのバージョンとの互換性を維持してきました」。
  • 手間も群を抜いて大きい方式です。ゲートと変換器を連結し、エンジンは最新の形式だけを計算して、バージョンごとの変換器が各レスポンスを以前の形式に変換します。過去の破壊的変更ごとに 1 つのモジュールが必要で、それらを永久に保守し続けます。
  • 効率性の評価では、すべての回で負けます。それでも次の 2 つの条件がそろえば、採用を検討してください。年に何度も破壊的変更を行いたいこと、そして移行を強制できないインテグレーターが長期にわたって存在することです。
  • 実際の API の規模と変更頻度を踏まえて判断してください。Stripe が採用しているという理由だけで、反射的に導入してはいけません。
• 降格ではなく、選択肢から削除：コンシューマーに連絡できず、破壊的変更を四半期ごと、またはそれより高い頻度ですでにリリースしている場合のバージョン管理なし。 インタビューの Q5 と Q4 の回答を合わせると、追加のみの進化は選択肢から外れます。変更頻度がすでに破っている「永久に」という約束を、警告できないコンシューマーベースに対して掲げることになるためです。最後に回すのではなく、メニューから削除してください。バージョン管理の仕組みの見積もりが上がってくるたびに、「気を付けて追加のみにすればよい」という案が計画として再び持ち上がるからです。再検討の条件は、破壊的変更の頻度が年におよそ 2 回を下回ること、またはコンシューマーベースを特定して連絡できるようになることです。
• Fielding の異論を明示します。同僚が持ち出すためです。 REST の学位論文の著者は、バージョニングのベストプラクティスは「しないこと」だと主張しています。進化可能なアーキテクチャにバージョン番号は不要であり、パスにバージョンを含めると、変化していないリソースの URL が変わるためです。バージョン管理なしの段階は、この主張に対する誠実な回答です。URI をデフォルトにするのは、実用性を重視した選択です。

この順位はデフォルトであり、絶対的な規則ではありません。インタビューの回答を踏まえて順位を見直してください。

• 厳しい期限（Q6）がある場合は、URI を上位にします。
• 何年も続く恒常的なポリシーで、変更の圧力が高い場合（Q4、Q7）は、日付ベースを上位にします。
• すでにアカウントごとの設定インフラを運用しているチームなら、Stripe 方式の固定化を、手間の評価で想定するより低コストで実現できます。

Q1 の回答が GraphQL の場合、このメニューは段階的な選択肢としては適用されません。継続的な進化はこのパラダイム自体のデフォルトポリシーであり、ランキングに含まれない隠れた第 6 の段階ではなく、議論のあるうえでのオプトアウトです。すべてのサーフェスにわたってバージョニングの方針を統一することが重要なら、文書化された移行先は Shopify の日付ベースのバージョン管理を行う GraphQL API です。

どの方式を選ぶにしても、バージョン指定のないアクセスをフォールバック経路として決して許可しないでください。Discord はそれを許可し、開発者は明確にアンチパターンだと指摘しました。後からバージョン指定のない経路を削除すること自体が、誰も同意していない破壊的変更になります。

4. 通知期間と同時に維持するバージョン数を設定する

対象者（インタビューQ2/Q5）に基づいて数値を設定し、references/notice-period-benchmarks.md にある公開ベンチマークと照らし合わせて確認します。

• 全面公開 API：非推奨化の通知期間を少なくとも 12 か月とします。Google Cloud と Shopify が一致する最低ラインです。
• 利用者がモバイルアプリを提供している場合、または利用者がエンタープライズの場合は、少なくとも 24 か月に延長します。Microsoft Graph と Meta が採用する最低ラインです。アプリストアの更新サイクルやエンタープライズの変更管理には時間がかかり、こちらでは制御できません。
• パートナー向け／B2B API： 公開ポリシーページではなく、契約書または SLA に期間を記載します。パートナーごとに交渉でき、文書に記載すれば強制力を持たせられます。
• 内部 API： 通知期間の代わりに、利用者主導のコントラクトテストと調整済みのデプロイを採用します。通知期間は利用者と直接調整できない場合の埋め合わせになりますが、内部チームなら調整できます。
• 同時に稼働させるバージョン数は 2〜3 個を上限とします（複数の情報源で一致する結論です）。稼働中のバージョンが増えるたびに、保守、テスト、ドキュメントのコストも増大します。Shopify は厳格な四半期ごとの自動化によって約 4 個を維持していますが、Salesforce の数十個は、積み重なったバージョンがもたらす問題を示す教訓です。
• 期間の起算日を定義します。バージョンのリリース日、次のバージョンのリリース日、または非推奨化の告知日のいずれかです。Meta の 2 年間の保証は、次の バージョンのリリース時に開始されます。この微妙な違いによって実際の日付が数か月ずれることがあります。ここが曖昧だと、後にサポートをめぐる争いにつながります。
• 公開した日付は確約として扱い、公開ベンチマークは最低ラインとします。 Salesforce は廃止を 2 年延期し、Twilio は EOL を 3 回延長しました。延期しても乗り切ることはできますが、コストがかかります。「最終」日付は最終ではないと、インテグレーターに学習させてしまうためです。外部のベンチマークを引用する際は、「正確に X か月」ではなく、必ず「少なくとも X か月」と記載します。

5. サンセットの告知を設計する

非推奨化は段階的なプロセスであり、単発のイベントではありません。告知からいきなり削除へ進んではいけません。

• 告知
• 非推奨化 - 両方のバージョンが稼働し、シグナルが有効です。
• サンセット - 期日を迎えます。
• 削除 - 猶予期間が終了します。

1. まず Deprecation ヘッダーを導入します（RFC 9745、標準化トラック、2025年3月）。非推奨化が予定されている、またはすでに始まっていることを示します。サンセットの日付がまだ決まっていなくても導入でき、この RFC では動作に変更を加えないことが明示されています。
2. 日付が確定したら Sunset ヘッダーを追加します（RFC 8594 - 情報提供目的であり、標準化トラックではありません。そのように記載してください）。非推奨化されたバージョンのレスポンスにのみ、そのバージョンが応答を停止する正確なタイムスタンプを設定します。
3. Link: rel="successor-version" を付けます（RFC 8288）。ツールが説明文を解析せずに後継バージョンを見つけられるようにし、OpenAPI ドキュメントでは deprecated: true を設定して、ドキュメントとコード生成に反映させます。
4. ヘッダーだけに頼ってはいけません。 ほとんどの API はこうしたヘッダーを使っておらず、「その理由はおもに文化的なもの」です。つまり、多くのインテグレーターのツールにも表示されません。ヘッダーに加えて、人に届くチャネルを少なくとも 1 つ組み合わせてください。変更履歴、開発者ダッシュボードのバナー、非推奨化されたバージョンをまだ呼び出しているアカウントを対象としたメール（samber/developer-platform-skills@integration-health-monitoring は、該当するインテグレーションとその担当者を特定し、期限までの連絡を行います）、またはレスポンス内の警告（Slack は API レスポンスのペイロードに非推奨化の通知を埋め込んでいます。影響が続いている呼び出し元に確実に届き、一斉告知より低コストです）。
5. 告知だけでなく、移行にも責任を持ちます。 チャーンルール：非推奨化する対象を所有しているなら、その利用者の移行にも責任を持ちます。具体的な手順を示す移行ガイド、実現可能であればツール、そしてサポートチャネルを用意してください。サンセットを告知してインテグレーターに対応を丸投げすることは、中間策ではなく、明確に名付けられた失敗パターンです。強制的な非推奨化（厳格な期限）は移行サポートを義務付けます。助言的な非推奨化（警告のみで、利用者は各自のタイミングで移行）は、保守コストやセキュリティリスクによって強制が正当化されるまでは、標準の対応です。

非推奨化の告知は、関連する samber/developer-platform-skills@api-status-communication と一部重なります。区分は次のとおりです。このスキルは、数か月にわたる計画的なバージョンライフサイクルの告知を扱い、もう一方は、プラットフォームで現在障害が発生している場合のインシデントやステータスページでの告知を扱います。

6. サンセット時の適用方法を選ぶ

実際に使われている方法は 2 つあり、RFC への準拠よりも、その選択のほうが重要です。

• ハードカットオフ（標準の推奨）： 廃止されたバージョンは、内容が明確に説明されたエラーを返します。Salesforce の「エンドポイントは無効化されています」というメッセージ、Twilio の 2008 API に対する 404、GitHub の 410 Gone がその例です。インテグレーターは、明確なエラーを診断して修正できます。
• ソフトなフォールフォワード： プラットフォームが、廃止されたバージョンを指定するリクエストを、引き続き利用可能な最も古いバージョンへルーティングします（Shopify が採用し、ドキュメント化しています）。停止よりも、利用者に気付かれない継続のほうが本当に安全なケースに限って採用し、目立つ形でドキュメント化してください。Meta の Graph API は、注意すべき事例です。「Meta はエラーを返しません。呼び出しを、まだ利用できる古いバージョンへひそかにルーティングします。その結果、アプリは動き続ける一方で、動作が裏で変化します。」ドキュメントに記載されていることと、利用者に気付かれていることは同じではありません。Meta のフォールフォワードはドキュメントに記載されていますが、動作が気付かれないまま変化することへの不満は依然として絶えません。
• いずれの場合も、サンセット日の後に、410 Gone を返す猶予期間を設けます。 接続を切断するのではなく、呼び出し元が診断できるエラーを返してください。無応答にしてはいけません。
• 適用方法は、プラットフォームの各面で異なっていてもかまいません。Meta の Marketing API は約 90 日の期間後に期限切れの呼び出しをハードエラーにしますが、中核となる Graph API は 2 年間フォールフォワードします。対象となる利用者の習熟度に応じて、方法を分けるのは妥当です。使い分ける場合は、両方の方法をポリシーに明記してください。

7. 影響範囲に応じたガバナンスを整備する

スキームの高度さではなく、ガバナンスの成熟度こそが、バージョンを円滑に廃止できるプラットフォームと、インシデントの事後検証を招くプラットフォームを分けます。段階は3つあります。順に成熟させていき、最初から最後の段階を採用しないでください。

1. 最低限：CIでの自動差分チェック／リンターと、担当エンジニアによる承認。 OpenAPIの差分チェックまたはリンター（Spectral、Zally、oasdiff）を組み込み、破壊的変更を機械的に検出します。フラグが立った項目はスタッフエンジニアが承認します。これは最低限であり、成熟した最終形ではありません。ステップ2の定義を差分チェックの重大度マップ、承認記録、公開される変更フィードに組み込むのが samber/developer-platform-skills@api-changelog-automation です。
2. 書面化された憲章を持つレビューボード：対象範囲がレビュー担当者1人では手に負えなくなった段階で設置します。AzureのBreaking Change Review Boardは承認を条件に仕様のマージを阻止します。特に参考にすべき点として、典型的な成果は承認／却下の判定ではなく、「現行顧客の動作を維持する代替設計」です。ゼロから作成するのではなく、Fuchsia API Councilの憲章を公開テンプレートとして活用できます。
3. プラットフォーム規模での包括的なガイドラインプログラム：GoogleのAIP（AIP-180／181は互換性と安定性を規定）、強制力のあるリンター、人が読んで理解できることの認証、設計レビューを整備します。Google自身が公開した「API Governance at Scale」の論文には、こうした階層が設けられた理由が記されています。手動レビューだけでは「うまく拡張できなかった」のです。

どの段階でも守るべきルールは同じです。ガバナンス層の承認なしに、破壊的変更をリリースしてはいけません。 AIP-181では、安定版APIに対するインプレースの破壊的変更は「極端な措置」とされ、ガバナンスチームの承認が必要です。段階的なモデルが置き換えようとしているのは、まさに非公式な根回しプロセスです。

8. 候補を出し合い、ポリシーを起草して検証する

ヒアリングのあと、すぐに完成した文書を書き上げないでください。

1. スキーム、期間、適用方法、ガバナンスを組み合わせた一貫性のあるポリシー案を2～3件提示します。軸ごとに個別に選べる案にせず、それぞれのトレードオフを明記し、理由とともに推奨案を示してください。案の例：Shopify型のカレンダーポリシー（四半期ごとのバージョン、12か月のサポート、後方移行）、GitHub型の保守的なポリシー（日付ベースのバージョン、24か月前の告知、厳格な410応答）、ステップ3の昇格条件を満たす場合のStripe型のピン留めポリシー。
2. ユーザーが案を選んだら、references/policy-document-template.mdに沿って、ポリシー文書をセクションごとに起草します。次のセクションに進む前に、各セクションをユーザーに確認してください。
   • スキーム
   • 定義
   • 期間
   • コミュニケーション
   • 適用方法
   • ガバナンス
   • 例外
3. 文書全体について明示的な承認を得てから、最終確定します。

障害パターン

以下はそれぞれ、文書化されている名前付きのインシデントパターンです。ドラフトポリシーがすべてに対応しているか確認してください。

• 同時に非推奨であり、デフォルトでもあるバージョン。 Discord は約1年半にわたり v6 を非推奨バージョンかつデフォルトバージョンとして提供し、その後、3つのバージョンを飛ばしてデフォルトを v10 に変更しました。新たに統合する開発者に非推奨バージョンを提供し続けると、非推奨という表示の信頼性が失われます。
• バージョン指定なしのアクセスを許可すること ― ステップ 3 を参照してください。後からこれをなくすと、計画外の破壊的変更になります。
• ビジネス上の都合でプロセスを省略すること。 Twitter/X は2023年の有料 API の終了について約7日間の猶予しか設けず、あらゆる基準の100分の1ほどの短さでした。しかも、デベロッパーリレーションズの担当者が解雇された後に実施され、料金を支払う意思のあった統合利用者にも影響しました。動機が技術的なものではない場合こそ、ガバナンスの規律が最も重要になります。まさにそのとき、プロセスを省略したい誘惑が最も強くなるからです。
• サンセット日の延期。 延期を繰り返すと（Twilio では3回延長）、統合利用者は日付を無視するようになります。
• ヘッダーだけでの告知 ― 誰のツールも読み取らないシグナルでは、RFC を満たしても誰にも届きません。
• 告知して放置すること ― Churn Rule 違反です。移行ガイドも、ツールも、対象を絞った連絡もありません。
• 文書化されていないフォールフォワード ― 実質的に、バグ報告が発生するのを待っている状態と区別できません。
• 起算点が定義されていないこと ― 2年間の開始時期を明示せずに「2年間サポート」とすることです（Meta では、次のリリースから起算します）。
• GraphQL の @deprecated を削除とみなすこと。 これはドキュメント上のシグナルです。削除するには、フィールドごとに実際の利用者がゼロであることを利用状況のテレメトリーで確認する必要があります。

測定

• テレメトリーから把握する破壊的変更の頻度：年に約2回を超える場合、方式か互換性の維持規律に問題があることを示しています（ステップ 2 の例外規定）。これは、このポリシーの継続的な健全性指標です。
• 移行完了の判断は利用状況に基づき、暦に基づかせないでください。 テレメトリーで実際のトラフィックがゼロ（または意識的に許容した残存トラフィックのみ）になった時点で、そのバージョンを削除できます。告知日が過ぎても、誰が移行したかは何も証明されません。
• 各告知後に非推奨バージョンのトラフィック比率が下がっているかどうかを追跡すれば、どのチャネルが統合利用者に実際に届いているかが分かります。一斉メール後も横ばいなら、サンセット日を迎えてインシデントになる前に、そのチャネルが機能していないと判断できます。
• 日付の遵守状況： 延期されたサンセット日の数を数えます。根拠となるデータによれば延期はよくあることです（Salesforce、Twilio）。それでも目標はゼロです。延期するたびに、今後設定するすべての日付の価値が損なわれるためです。トラフィック指標には業界基準がないため、最初の非推奨化サイクルでベースラインを設定し、それを基に改善してください。

呼び出し例

• 「公開 REST API のバージョニングと非推奨化のポリシーを作成してください。これまでポリシーがなく、破壊的変更が予定されています。」
• 「来年 /v1 を廃止します。サンセットまでのタイムライン、告知計画、移行しない呼び出し元への対応を設計してください。」
• 「GraphQL API は REST API のようにバージョニングすべきですか。それとも継続的に進化させるべきですか。いずれの場合もポリシー案を作成してください。」

参考資料

• references/versioning-case-studies.md - Stripe のゲート／トランスフォーマーの仕組み、保守的なプラットフォーム（Shopify、LinkedIn、AWS、Azure、Google Maps、PayPal/Braintree）、そして教訓となる事例（Meta、Discord、Twitter/X）。
• samber/developer-platform-skills@api-error-design - エラーコードも API 契約の一部です。エラーコードの廃止には、このスキルの非推奨化の仕組みを適用します。
• samber/developer-platform-skills@webhook-platform-design - イベントスキーマの進化には、ここで定義するものと同じ破壊的変更の定義と告知の規律が適用されます。
• samber/developer-platform-skills@public-graphql-api-design - ステップ 1 の継続的な進化の道筋を可能にする、スキーマ側の設計です（追加に対応しやすいペイロード、結果のユニオン、@deprecated フィールドの移行）。このスキルでは、削除時に従う告知の規律を定めています。
• samber/developer-platform-skills@bulk-data-sharing-design - 一括ファイル／データレイクのエクスポートでは、このスキルの API 非推奨化の仕組みではなく、別途定める追加のみ可能な契約に基づいてスキーマを進化させます。
• samber/developer-platform-skills@sdk-package-publishing - SDK パッケージのバージョン、プレリリースチャネル、レジストリでの非推奨化について扱います。ここで定める API バージョンとは切り離されています。
• samber/developer-platform-skills@public-roadmap-strategy - パブリックロードマップでは、このポリシーによる告知があるまで非推奨化を掲載せず、告知後は双方に相互リンクを設定します。