Stripe APIのバージョニングの仕組みと、真似すべき点

Stripe APIのバージョニングは日付で動く。すべてのアカウントはリリース日にちなんだ名前のAPIバージョンに固定され、個々のリクエストは Stripe-Version ヘッダーでその固定を上書きできる。執筆時点(2026年10月)でStripeのドキュメントにある最新バージョンは 2026-09-30.endive で、同じ仕組みは、はるかに小さなAPIでも週末で真似できる。

以下のStripeに関する事実はすべてStripe自身のページに基づいており、使った箇所にリンクを付けている。

Stripe APIのバージョニングはどう動くのか

StripeはすべてのアカウントにデフォルトのAPIバージョンを与え、バージョンを指定しないリクエストはすべてそれを使う。いつ移行するかは呼び出し側が選ぶ。デフォルトを変更するか、個々のリクエストにバージョンを設定する。

Stripeのエンジニアリングの記事によれば、アカウントは最初にAPIリクエストを行ったときに固定される。アカウントは「利用可能な最新バージョンに自動的に固定され」、それ以降のすべての呼び出しには、暗黙のうちにそのバージョンが割り当てられる。

バージョン文字列は日付だ。2024-09-30.acacia リリース以降は名前も付き、2026-09-30.endive のようになる。日付はバージョンの順序を決め、名前は、そのバージョンがどのメジャーリリースのファミリーに属するかを示す。

リクエストごとにバージョンを選ぶには

リクエストに Stripe-Version ヘッダーを送るか、SDKでバージョンを設定する。Stripeのアップグレードガイドにはヘッダーの形式が示されており、同じ呼び出しが本番環境でもテスト環境でも使える。

curl https://api.stripe.com/v1/charges \
  -u "$STRIPE_SECRET_KEY:" \
  -H "Stripe-Version: 2026-09-30.endive"

Stripeのガイドによれば、SDKでバージョンをグローバルに、またはリクエストごとに設定すると、レスポンスオブジェクトはそのバージョンで返ってくる。

Stripeは、アカウントのデフォルトに頼らないことも勧めている。リクエストごとに、ヘッダーか固定したSDKでバージョンを指定すべきだというのだ。そうすれば、バージョンを決めるのはダッシュボードの設定ではなく、コードになる。

SDKの固定のされ方は言語によって違う。ドキュメントによれば、動的型付け言語のライブラリの最近のバージョンは、そのSDKがリリースされた時点の最新のAPIバージョンを使い、静的型付けのもの(Java、Go、.NET)はそれに固定されている。ライブラリのバージョンをインストールすることは、事実上、APIバージョンを選ぶことだ。

バージョンが変わるとWebhookはどうなるのか

Webhookイベントは、サーバーコードが使うバージョンではなく、そのエンドポイントに紐づいたAPIバージョンで生成される。Stripeのドキュメントによれば、イベントはエンドポイントの作成時に設定されたバージョンを使い、設定がなければアカウントのデフォルトを使う。SDKのバージョンを変えても、Webhookハンドラーが受け取るものは変わらない。

そのため、リクエストの経路とイベントの経路は、別々のバージョンに置かれることがある。イベントの送信先では、snapshot_api_version は送信先を作成するときにしか設定できないので、別のバージョンにするには新しい送信先が必要になる。

この移行のためのStripeの手順は、並行運用だ。目標バージョンで新しいエンドポイントを作り、同じイベントを両方に送り、ハンドラーが片方を処理してもう片方を無視するようにしてから、切り替えて古いエンドポイントを無効にする。重複期間中はすべてのイベントが二度届くので、ハンドラーは冪等でなければならない。これはイベントを発行するどんなAPIにも真似する価値のあるパターンで、それが必要になるペイロードの変更を告知する場所が、Webhookのチェンジログだ。

月次リリースとメジャーリリースとは何か

2024-09-30.acacia リリース以降、Stripeは破壊的変更のない新しいAPIバージョンを毎月リリースし、年に2回、破壊的変更を含むバージョンから始まる新しいメジャーリリースを出す。バージョニングのページによれば、月次リリースにはコードを更新せずにアップグレードできるが、メジャーリリースでは変更が必要になることがある。

メジャーリリースには名前が付く。バージョニングのページはBasilを例に挙げており、このプロセスについてのStripeの発表では、名前は植物に由来し、Acaciaから始まるとされている。月次リリースは直前のメジャーリリースの名前を引き継ぐので、名前がそのままアップグレードしても安全であることを示す。Stripeの変更履歴には使われている名前が並んでおり、執筆時点で最新のエントリは 2026-09-30.endive だ。

つまり、日付は「どのくらい新しいか」に答え、名前は「これは破壊的変更の境目か」に答える。Stripeの発表には例外の余地も残されている。それがなければ連携が深刻な影響を受ける場合には、サイクル外で破壊的変更を出す権利を留保しているのだ。この発表はStripeの新しいAPIリリースプロセスにある。

Stripe APIの最新バージョンは何か

執筆時点(2026年10月)で、Stripeのバージョニングのページは、現在のバージョンを 2026-09-30.endive と記しており、変更履歴も同じバージョンを最新としている。Stripeは毎月新しいバージョンを公開するので、記事に印刷された文字列はすぐに古くなる。何かを固定する前に、最新の変更履歴を読み、テストしたバージョンを固定すること。

Stripeはどうやって古いバージョンを動かし続けているのか

Stripeは、すべての破壊的変更を、自己完結したバージョン変更モジュールとして書き、データの最新の形から逆向きにそれらのモジュールを適用することで、古いバージョンを動かし続けている。その仕組みはAPIバージョニングについてのエンジニアリングの記事に書かれている。

各モジュールは、何を変えるかを宣言し、変更を文書化し、変換関数を含む。記事の例では、フィールドが文字列からハッシュに変わる。レスポンスを作るには、システムは目標のバージョンを割り出し、そこから時間をさかのぼって、途中で見つけた各モジュールを、そのバージョンに到達するまで適用する。

この設計からは二つの副次的な効果が生まれ、記事はどちらも挙げている。モジュールが触れるフィールドとリソースを宣言するので、Stripeはデプロイ時にそこからAPIの変更履歴を生成できる。そして、アカウントのバージョンが分かっているので、ドキュメントをそれに合わせて調整し、そのバージョン以降の後方互換性のない変更について警告できる。

コストはどのくらいで、小さなAPIは何を真似すべきか

バージョニングにはエンジニアリングの注意力というコストがかかり、Stripe自身もそう述べている。エンジニアリングの記事は、保守の負担を認めたうえで、新しいコードを書くときに古い挙動について考える必要が少ないほど良い、という目標を述べている。また、そもそもバージョン変更を必要としないよう、リリース前に軽量なAPIレビューを行うことも説明している。

小さなAPIは、古いバージョンごとにモジュールの連鎖を持つ余裕はなく、その必要もない。価値を運ぶ部分を真似すればよい。

1. 日付付きのバージョン。 日付なら何が「メジャー」かの判断が要らず、呼び出し側も読める。URL方式やヘッダー方式との比較は、バージョニングのベストプラクティスの記事にある。
2. 固定されたデフォルト。 アカウントまたはキーを、最初に使った時点のバージョンに固定し、動いている連携の下でAPIが変わらないようにする。
3. リクエストごとの上書き。 呼び出し側が、確定する前に、本番環境で一回の呼び出しに新しいバージョンを試せるヘッダー。
4. Webhookエンドポイントのバージョン。 イベントのペイロードは、呼び出し側が最も驚かされる場所だ。
5. バージョンごとに一つのチェンジログエントリ。 バージョン、日付、誰が影響を受けるか、何をすべきかを書く。何が破壊的変更にあたるかは、そもそも何が新しいバージョンに入るかを判断する基準で、エントリそのものはAPIチェンジログの記事で扱っている。

サポートするバージョンの数が必要に迫るまで、モジュールの連鎖は作らない。稼働中のバージョンが二つか三つなら、いくつかの分岐と廃止日で処理でき、その手順はAPIバージョンの廃止で説明している。

日付付きのチェンジログを公開するなら、バージョンの履歴はエントリの質で決まる。Changeloopでは、マージされたプルリクエストごとにエントリの下書きが作られ、チェンジログのページとフィードに公開される前に、人が承認するまで保留される。バージョンごとのエントリはここで書かれ、一つだけの人によるゲートが、呼び出し側が何をすべきかを確認するレビューになる。

FAQ

Stripe APIの最新バージョンは何か? 執筆時点(2026年10月)で、Stripeのバージョニングのページは、現在のバージョンを 2026-09-30.endive と記している。Stripeは毎月新しいバージョンを出すので、固定する前に変更履歴を確認し、アカウントのデフォルトに頼らずに、バージョンをコードに書き込むこと。

リクエストにStripe APIのバージョンを設定するには? Stripe-Version ヘッダー(たとえば Stripe-Version: 2026-09-30.endive)を送るか、サーバー側のSDKでグローバルに、またはリクエストごとにバージョンを設定する。どちらもなければ、リクエストはアカウントのデフォルトバージョンを使い、それはWorkbenchで自分で設定する。

Webhookはリクエストと同じStripe APIバージョンを使うのか? 必ずしもそうではない。Webhookイベントは、エンドポイントの作成時に設定されたバージョンを使い、設定がなければアカウントのデフォルトを使う。SDKをアップグレードしても、Webhookハンドラーが受け取るペイロードは変わらないので、エンドポイントは別にアップグレードし、並行してテストする。

Stripe方式の日付によるバージョニングは小さなAPIに向いているか? 日付付きのバージョン、固定されたデフォルト、リクエストごとのヘッダー、バージョンごとに一つのチェンジログエントリは、安上がりで真似する価値がある。内部のバージョン変更モジュールの連鎖は、多くの古いバージョンを同時にサポートするまでは不要だ。稼働中のバージョン二つと、古いほうの廃止日から始めるといい。

この記事の技術的な記述は第三者による確認を受けていません。誤りがあればお知らせください。修正します。

changeloopの関連ページ： 開発者向けドキュメント