Wersjonowanie API Stripe: jak działa i co z niego skopiować

Wersjonowanie API Stripe działa według dat. Każde konto jest przypięte do wersji API nazwanej od daty wydania, a każde pojedyncze żądanie może to przypięcie nadpisać nagłówkiem Stripe-Version. W chwili pisania (październik 2026) bieżącą wersją w dokumentacji Stripe jest 2026-09-30.endive, a ten sam schemat może skopiować znacznie mniejsze API w jeden weekend.

Każdy fakt o Stripe poniżej pochodzi ze stron samego Stripe, podlinkowanych tam, gdzie go użyto.

Jak działa wersjonowanie API Stripe?

Stripe daje każdemu kontu domyślną wersję API, a każde żądanie, które nie podaje wersji, jej używa. Wywołujący sami wybierają, kiedy przejść dalej, zmieniając wersję domyślną albo ustawiając wersję w pojedynczych żądaniach.

Post inżynierski Stripe mówi, że konto jest przypinane przy pierwszym żądaniu API: jest “automatically pinned to the most recent version available”, a od tej chwili każde wywołanie dostaje tę wersję domyślnie.

Ciąg wersji to data. Od wydania 2024-09-30.acacia niesie też nazwę, jak w 2026-09-30.endive. Data porządkuje wersje, a nazwa mówi, do której rodziny wydań głównych należy dana wersja.

Jak wybrać wersję dla pojedynczego żądania?

Wyślijcie nagłówek Stripe-Version w żądaniu albo ustawcie wersję w SDK. Przewodnik aktualizacji Stripe pokazuje formę z nagłówkiem, a to samo wywołanie działa w środowiskach live i testowym.

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

Przewodnik Stripe zauważa, że gdy ustawiacie wersję globalnie lub w żądaniu w SDK, obiekty odpowiedzi wracają w tej wersji.

Stripe odradza też opieranie się na wersji domyślnej konta. Jego słowami: podawajcie wersję przy każdym żądaniu, nagłówkiem lub przypiętym SDK, tak by to wasz kod decydował o wersji, a nie ustawienie w panelu.

SDK przypinają wersje różnie w zależności od języka. Dokumentacja mówi, że najnowsze wersje bibliotek dla języków dynamicznie typowanych używają wersji API, która była najnowsza, gdy wyszło dane wydanie SDK, a silnie typowane (Java, Go i .NET) są do niej na sztywno przypięte. Instalacja wersji biblioteki to w praktyce wybór wersji API.

Co dzieje się z webhookami, gdy wersja się zmienia?

Zdarzenie webhooka jest renderowane w wersji API przypisanej do jego endpointu, a nie w wersji, której używa kod waszego serwera. Dokumentacja Stripe mówi, że zdarzenia używają wersji ustawionej przy tworzeniu endpointu, a w przeciwnym razie domyślnej wersji konta. Zmiana wersji SDK nie zmienia tego, co dostaje wasz handler webhooka.

Ścieżka żądań i ścieżka zdarzeń mogą więc leżeć na dwóch różnych wersjach. W przypadku miejsc docelowych zdarzeń snapshot_api_version ustawiacie tylko przy tworzeniu miejsca docelowego, więc inna wersja oznacza nowe miejsce docelowe.

Ścieżka aktualizacji Stripe dla tego przypadku to uruchomienie równoległe. Tworzycie nowy endpoint w docelowej wersji, wysyłacie te same zdarzenia do obu, uczycie handler przetwarzać jeden i ignorować drugi, potem przełączacie i wyłączacie stary endpoint. Ponieważ w czasie nakładania się każde zdarzenie przychodzi dwa razy, handler musi być idempotentny. To dobry wzorzec do skopiowania dla każdego API, które emituje zdarzenia, a changelog webhooka to miejsce, w którym ogłaszacie zmiany payloadu, które go wymuszają.

Czym są wydania miesięczne i główne?

Od wydania 2024-09-30.acacia Stripe wydaje nową wersję API co miesiąc bez zmian łamiących i dwa razy w roku wydaje nowe wydanie główne, które zaczyna się od wersji zawierającej zmiany łamiące. Strona o wersjonowaniu mówi, że możecie przejść na dowolne wydanie miesięczne bez aktualizowania kodu, podczas gdy wydanie główne może wymagać zmian.

Wydania główne mają nazwy. Strona o wersjonowaniu podaje jako przykład Basil, a ogłoszenie Stripe o tym procesie mówi, że nazwy pochodzą od roślin, zaczynając od Acacia, a wydania miesięczne zachowują nazwę poprzedzającego je wydania głównego, żeby nazwa sygnalizowała, że można na nie bezpiecznie przejść. Changelog Stripe wylicza używane nazwy, a w chwili pisania najnowszy wpis to 2026-09-30.endive.

Data odpowiada więc na pytanie “jak nowa”, a nazwa na pytanie “czy to granica zmian łamiących”. Ogłoszenie Stripe zostawia też miejsce na wyjątki: zastrzega sobie prawo do wydania zmiany łamiącej poza cyklem, gdy integracja bez niej byłaby poważnie dotknięta. Ogłoszenie jest pod Stripe’s new API release process.

Jaka jest najnowsza wersja API Stripe?

W chwili pisania (październik 2026) strona Stripe o wersjonowaniu stwierdza, że bieżąca wersja to 2026-09-30.endive, a jego changelog wymienia tę samą wersję jako najnowszą. Stripe publikuje nową wersję co miesiąc, więc każdy ciąg wydrukowany w artykule szybko się starzeje. Przeczytajcie aktualny changelog, zanim cokolwiek przypniecie, i przypnijcie wersję, z którą testowaliście.

Jak Stripe utrzymuje stare wersje przy życiu?

Stripe utrzymuje stare wersje, zapisując każdą zmianę łamiącą jako samodzielny moduł zmiany wersji i stosując moduły wstecz, od najnowszego kształtu danych. Opisuje to jego post inżynierski o wersjonowaniu API.

Każdy moduł deklaruje, co zmienia, dokumentuje zmianę i zawiera funkcję transformacji. Post podaje przykład pola zmieniającego się z ciągu znaków na hash. Aby zbudować odpowiedź, system ustala wersję docelową, potem cofa się w czasie i stosuje każdy napotkany po drodze moduł, aż dotrze do tej wersji.

Z tego projektu wynikają dwa efekty uboczne i post wymienia oba. Ponieważ moduły deklarują pola i zasoby, których dotykają, Stripe może generować swój changelog API z nich przy wdrożeniu. A ponieważ wersja konta jest znana, dokumentacja może się do niej dopasować i ostrzegać przed niezgodnymi wstecz zmianami od tej wersji.

Ile to kosztuje i co powinno skopiować mniejsze API?

Wersjonowanie kosztuje uwagę inżynierów i Stripe tak mówi. Post inżynierski przyznaje się do kosztu utrzymania i stawia cel: im mniej trzeba myśleć o starym zachowaniu podczas pisania nowego kodu, tym lepiej. Opisuje też lekkie przeglądy API przed wydaniem, by w ogóle nie potrzebować zmiany wersji.

Małe API nie stać na łańcuch modułów dla każdej starej wersji i go nie potrzebuje. Skopiujcie części, które niosą wartość:

1. Wersje z datą. Data nie wymaga oceny, co liczy się jako “główne”, a wywołujący potrafią ją odczytać. Artykuł o najlepszych praktykach wersjonowania API porównuje to ze schematami w URL i nagłówku.
2. Przypięta wersja domyślna. Przypnijcie konto lub klucz do wersji przy pierwszym użyciu, tak by API nigdy nie przesuwało się pod działającą integracją.
3. Nadpisanie w żądaniu. Nagłówek, który pozwala wywołującemu przetestować nową wersję na jednym wywołaniu, na produkcji, zanim się do niej zobowiąże.
4. Wersja na endpoincie webhooka. Payloady zdarzeń to miejsce, w którym wywołujących zaskakuje się najczęściej.
5. Jeden wpis changelogu na wersję. Niech podaje wersję, datę, kogo to dotyczy i co zrobić. Co jest zmianą łamiącą to test na to, co w ogóle należy do nowej wersji, a artykuł o changelogu API opisuje sam wpis.

Pomińcie łańcuch modułów, dopóki liczba obsługiwanych wersji nie zmusi was do niego. Dwie lub trzy żywe wersje obsłużycie kilkoma rozgałęzieniami i datą końca, co omawia wygaszanie wersji API.

Jeśli publikujecie changelog z datami, historia wersji jest tak dobra, jak jej wpisy. W Changeloop szkic wpisu powstaje z każdego scalonego pull requesta i czeka na zatwierdzenie przez człowieka, zanim zostanie opublikowany na stronie changelogu i w kanale. Tam pisze się wpis dla wersji, a jedyną bramką człowieka jest przegląd, który mówi, co wywołujący musi zrobić.

FAQ

Jaka jest najnowsza wersja API Stripe? W chwili pisania (październik 2026) strona Stripe o wersjonowaniu stwierdza, że bieżąca wersja to 2026-09-30.endive. Stripe wydaje nową wersję co miesiąc, więc sprawdźcie jego changelog przed przypięciem i zapiszcie wersję w kodzie, zamiast polegać na wersji domyślnej konta.

Jak ustawić wersję API Stripe w żądaniu? Wyślijcie nagłówek Stripe-Version, na przykład Stripe-Version: 2026-09-30.endive, albo ustawcie wersję w serwerowym SDK globalnie lub w pojedynczym żądaniu. Bez jednego i drugiego żądanie używa domyślnej wersji konta, którą ustawiacie w Workbench.

Czy webhooki używają tej samej wersji API Stripe co moje żądania? Niekoniecznie. Zdarzenia webhooków używają wersji ustawionej przy tworzeniu endpointu, a jeśli jej nie ustawiono, domyślnej wersji konta. Aktualizacja SDK nie zmienia payloadu, który dostaje wasz handler webhooka, więc aktualizujcie endpointy osobno i testujcie je równolegle.

Czy wersjonowanie datami w stylu Stripe pasuje do małego API? Wersje z datą, przypięta wersja domyślna, nagłówek w żądaniu i jeden wpis changelogu na wersję są tanie i warte skopiowania. Wewnętrzny łańcuch modułów zmiany wersji nie, dopóki nie obsługujecie wielu starych wersji naraz. Zacznijcie od dwóch żywych wersji i daty końca dla starszej.

Twierdzenia techniczne w tym artykule nie zostały niezależnie zweryfikowane. Jeśli coś się nie zgadza, daj nam znać, a poprawimy to.

Powiązane w changeloop: Dokumentacja dla deweloperów