Stripe の API バージョニングは『業界標準の参考例』
Stripe は API バージョニングのベストプラクティスとして広く参照されています。本記事では編集部の視点で、Stripe 流の進化的設計を公開情報をもとに整理します。API バージョニング基礎 もご参考に。
Stripe の Date-based バージョニング
(1) 2024-12-01 形式のバージョン。(2) アカウント単位で指定。(3) Stripe-Version ヘッダ。(4) 未指定時はアカウントのデフォルト。(5) 段階的に新バージョン採用。
後方互換性の維持
(1) フィールド追加は OK。(2) 変換層：古い形式↔新しい形式。(3) 動作の変更もバージョンで分岐。(4) 削除は段階的廃止。(5) old version も何年も維持(公開情報をもとに)。
進化的設計の原則
(1) nullable で拡張余地。(2) enum は文字列で開放。(3) discriminator pattern。(4) configurations 経由で動作切替。(5) experimental フィールド：徐々に公式化。
廃止プロセス
(1) Deprecation announcement。(2) 移行ガイド。(3) 2年程度の維持(公開情報をもとに)。(4) 利用統計確認。(5) 個別通知：主要顧客。Webhook 設計 もご参考に。
クライアント SDK の役割
(1) SDK でバージョン抽象化。(2) 自動アップデート。(3) 後方互換性のクッション。(4) 型変換。(5) 多言語対応。SDK 提供がエコシステムの鍵。
実装パターン
(1) middleware で変換。(2) resource ごとのバージョン管理。(3) テスト：全バージョン回帰テスト。(4) 監視：バージョン別利用率。(5) ドキュメント：バージョン別。REST API 設計 もご参考に。
失敗しがちなパターン
(1) 破壊変更で前触れなし。(2) old version の早期廃止。(3) 変換層の保守困難：負債化。(4) SDK 未整備：消費者の負担大。(5) 監視なし：影響範囲不明。対策は、(1)2年プレアナウンス、(2)長期維持、(3)変換ロジック整理、(4)SDK 必須、(5)バージョン別利用統計、です。