Verzování API Stripe: jak funguje a co z něj převzít

Verzování API Stripe funguje podle data. Každý účet je připnutý k verzi API pojmenované podle data vydání a každý jednotlivý požadavek může toto připnutí přepsat hlavičkou Stripe-Version. V době psaní (říjen 2026) je aktuální verze v dokumentaci Stripe 2026-09-30.endive a stejné schéma může převzít mnohem menší API za víkend.

Každý fakt o Stripe níže pochází z vlastních stránek Stripe, s odkazem tam, kde je použit.

Jak funguje verzování API Stripe?

Stripe dává každému účtu výchozí verzi API a každý požadavek, který verzi nejmenuje, ji používá. Volající si vybírají, kdy se přesunou, změnou výchozí verze nebo nastavením verze u jednotlivých požadavků.

Technický článek Stripe říká, že účet se připne při prvním požadavku na API: je «automaticky připnut k nejnovější dostupné verzi» a od té chvíle je každému volání tato verze přiřazena implicitně.

Řetězec verze je datum. Od vydání 2024-09-30.acacia nese i název, jako v 2026-09-30.endive. Datum verze řadí a název říká, do které rodiny hlavních vydání verze patří.

Jak zvolit verzi pro jednotlivý požadavek?

Pošlete hlavičku Stripe-Version s požadavkem nebo nastavte verzi v SDK. Průvodce upgradem Stripe ukazuje tvar s hlavičkou a stejné volání funguje v živém i testovacím prostředí.

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

Průvodce Stripe uvádí, že když verzi nastavíte v SDK globálně nebo pro jednotlivý požadavek, objekty odpovědí se vrátí v této verzi.

Stripe také doporučuje nespoléhat na výchozí verzi účtu. Jeho slovy: uvádějte verzi u každého požadavku, hlavičkou nebo připnutým SDK, aby verzi určoval váš kód a ne nastavení v dashboardu.

SDK se připínají podle jazyka různě. Dokumentace říká, že nedávné verze dynamicky typovaných knihoven používají verzi API, která byla nejnovější, když toto vydání SDK vyšlo, a silně typované (Java, Go a .NET) jsou k ní pevně svázané. Instalace verze knihovny je tak fakticky volbou verze API.

Co se stane s webhooky, když se změní verze?

Událost webhooku se vykreslí ve verzi API připojené k jejímu endpointu, ne ve verzi, kterou používá váš serverový kód. Dokumentace Stripe říká, že události používají verzi nastavenou při vytvoření endpointu a jinak výchozí verzi účtu. Změna verze SDK nemění, co dostává váš handler webhooků.

Cesta vašich požadavků a cesta událostí tak mohou stát na dvou různých verzích. U cílů událostí nastavujete snapshot_api_version jen při vytvoření cíle, takže jiná verze znamená nový cíl.

Cesta upgradu u Stripe je paralelní běh. Vytvořte nový endpoint v cílové verzi, posílejte stejné události oběma, naučte handler jednu zpracovat a druhou ignorovat, pak přepněte a starý endpoint vypněte. Protože každá událost během překryvu přijde dvakrát, musí být handler idempotentní. To je dobrý vzor k převzetí pro jakékoli API, které vysílá události, a changelog webhooků je místo, kde oznamujete změny payloadu, které ho činí nutným.

Co jsou měsíční a hlavní vydání?

Od vydání 2024-09-30.acacia Stripe vydává novou verzi API měsíčně bez zásadních změn a dvakrát ročně nové hlavní vydání, které začíná verzí obsahující zásadní změny. Stránka o verzování říká, že na jakékoli měsíční vydání můžete přejít bez úpravy kódu, zatímco hlavní vydání může vyžadovat změny.

Hlavní vydání nesou jména. Stránka o verzování uvádí jako příklad Basil a oznámení procesu od Stripe říká, že jména pocházejí z rostlin, počínaje Acacia, a že měsíční vydání si ponechávají jméno předchozího hlavního vydání, aby jméno signalizovalo, že jsou bezpečná k přechodu. Changelog Stripe uvádí používaná jména a v době psaní je nejnovějším záznamem 2026-09-30.endive.

Datum tedy odpovídá na «jak nové» a jméno na «je to hranice zásadní změny». Oznámení Stripe také nechává prostor pro výjimky: vyhrazuje si právo vydat zásadní změnu mimo cyklus, kde by integrace bez ní byla vážně zasažena. Oznámení je na Stripe’s new API release process.

Jaká je nejnovější verze API Stripe?

V době psaní (říjen 2026) stránka Stripe o verzování uvádí, že aktuální verze je 2026-09-30.endive, a jeho changelog uvádí tutéž verzi jako nejnovější. Stripe vydává novou verzi měsíčně, takže jakýkoli řetězec vytištěný v článku rychle stárne. Než něco připnete, přečtěte si živý changelog a připněte verzi, proti které jste testovali.

Jak Stripe udržuje staré verze funkční?

Stripe udržuje staré verze naživu tak, že každou zásadní změnu píše jako samostatný modul změny verze a moduly aplikuje zpětně od nejnovějšího tvaru dat. Mechanismus popisuje jeho technický článek o verzování API.

Každý modul deklaruje, co mění, změnu dokumentuje a obsahuje transformační funkci. Článek uvádí příklad pole, které se mění z řetězce na hash. Pro sestavení odpovědi systém zjistí cílovou verzi, pak se vrací v čase a aplikuje každý modul, který cestou najde, dokud nedorazí k této verzi.

Z toho návrhu plynou dva vedlejší efekty a článek pojmenovává oba. Protože moduly deklarují pole a zdroje, kterých se dotýkají, může Stripe z nich při nasazení generovat svůj changelog API. A protože je verze účtu známa, dokumentace se jí může přizpůsobit a varovat před zpětně nekompatibilními změnami od této verze.

Kolik to stojí a co by mělo převzít menší API?

Verzování stojí pozornost inženýrů a Stripe to říká. Technický článek uznává břemeno údržby a uvádí cíl, že čím méně přemýšlení staré chování vyžaduje při psaní nového kódu, tím lépe. Popisuje také lehké revize API před vydáním, aby se změně verze dalo vůbec vyhnout.

Malé API si nemůže dovolit řetěz modulů pro každou starou verzi a nepotřebuje ho. Převezměte části, které nesou hodnotu:

1. Datované verze. Datum nevyžaduje úsudek o tom, co se počítá jako «hlavní», a volající ho umí přečíst. Článek o nejlepších postupech verzování API to srovnává se schématy v URL a v hlavičce.
2. Připnutá výchozí verze. Zafixujte účet nebo klíč na verzi při prvním použití, aby se API nikdy nepohnulo pod fungující integrací.
3. Přepsání pro požadavek. Hlavička, která volajícímu dovolí vyzkoušet novou verzi na jednom volání, v produkci, než se zaváže.
4. Verze na endpointu webhooku. Payloady událostí jsou místo, kde jsou volající překvapeni nejvíc.
5. Jeden záznam changelogu na verzi. Ať jmenuje verzi, datum, koho se týká a co dělat. Co se počítá jako zásadní je test toho, co do nové verze vůbec patří, a článek o changelogu API pokrývá samotný záznam.

Řetěz modulů vynechte, dokud ho nevynutí počet podporovaných verzí. Dvě nebo tři živé verze zvládnete několika větvemi a datem ukončení, což provádí článek ukončení verze API.

Pokud publikujete datovaný changelog, historie verzí je jen tak dobrá jako její záznamy. V Changeloop se z každého sloučeného pull requestu vytvoří návrh záznamu a drží se, dokud ho člověk neschválí, než se zveřejní na stránce changelogu a ve feedu. Tam se píše záznam pro verzi a jedinou lidskou bránou je revize, která říká, co musí volající udělat.

FAQ

Jaká je nejnovější verze API Stripe? V době psaní (říjen 2026) stránka Stripe o verzování uvádí, že aktuální verze je 2026-09-30.endive. Stripe vydává novou verzi měsíčně, takže před připnutím zkontrolujte jeho changelog a verzi zapište do kódu místo spoléhání na výchozí verzi účtu.

Jak nastavit verzi API Stripe u požadavku? Pošlete hlavičku Stripe-Version, například Stripe-Version: 2026-09-30.endive, nebo nastavte verzi ve svém serverovém SDK globálně či pro jednotlivý požadavek. Bez jedné z těchto možností požadavek používá výchozí verzi vašeho účtu, kterou nastavujete ve Workbench.

Používají webhooky stejnou verzi API Stripe jako moje požadavky? Nemusí. Události webhooků používají verzi nastavenou při vytvoření endpointu a výchozí verzi účtu, pokud žádná nebyla nastavena. Upgrade SDK nemění payload, který dostává váš handler webhooků, takže endpointy upgradujte zvlášť a testujte je paralelně.

Hodí se datové verzování ve stylu Stripe pro malé API? Datované verze, připnutá výchozí verze, hlavička pro požadavek a jeden záznam changelogu na verzi jsou levné a stojí za převzetí. Interní řetěz modulů změn verze ne, dokud nepodporujete mnoho starých verzí najednou. Začněte se dvěma živými verzemi a datem ukončení té starší.

Technická tvrzení v tomto článku nikdo nezávisle neověřil. Pokud tu něco nesedí, dej nám vědět a opravíme to.

Související na changeloop: Dokumentace pro vývojáře