APIバージョン管理

後方互換性ルール

これらのルールは、/api/v1のすべてのエンドポイントにおいて何が安全で何が破壊的変更であるかを説明します。

レスポンスフィールド

• フィールドの追加は非破壊的変更です — クライアントは不明なフィールドを無視します。
• フィールドの削除は破壊的変更です — 新しいAPIバージョンが必要です。
• フィールドの名前変更は破壊的変更です — 新しいAPIバージョンが必要です。
• フィールドの型変更（例：文字列 → 数値）は破壊的変更です — 新しいAPIバージョンが必要です。

クエリパラメーター

• オプションのクエリパラメーターの追加は非破壊的変更です。
• オプションのクエリパラメーターの削除は破壊的変更です — それに依存するクライアントは機能がサイレントに失われます。

非推奨ポリシー

新しいメジャーAPIバージョンをリリースすると、以前のバージョンは文書化されたサンセットパスに入ります。

• 非推奨発表からサポート終了までの最低6ヶ月間の通知期間。
• 非推奨期間中、すべてのレスポンスにはRFC 9745 Deprecationヘッダー（?1）とRFC 8594 Sunsetヘッダー（EOLのHTTP日付）が含まれます。
• サンセットの30日前からブラウンアウトが開始されます。これは、残存する統合を表面化させるために、リクエストのごく一部が503 Service Unavailableを返すものです。この割合は期間中に0%から25%に増加します。
• 過去30日間に非推奨バージョンにアクセスしたAPIキーを持つ開発者には、メジャーバージョン移行ごとに1回メールが送信されます。
• サンセット日以降、バージョンは削除され、それへのリクエストは404を返します。