Nejlepší praktiky verzování API, kvůli volajícím

Verzování API je praxe udržování starého kontraktu funkčního poté, co jste ho změnili, aby volající mohli přejít podle vlastního harmonogramu, ne toho vašeho. Ta věta obsahuje dvě rozhodnutí, na kterých záleží: co se počítá jako změna kontraktu, a jak dlouho ten starý dál funguje. Kde žije číslo verze, o čem je většina debat o verzování, je nejméně důležité ze tří a nejsnáz se dělá správně.

Kdy by se mělo API verzovat?

Verzujte API jen tehdy, když by změna rozbila korektního volajícího. Aditivní změny, nová pole, nové endpointy, nové volitelné parametry nepotřebují verzi; volající napsaní proti starému kontraktu dál fungují a nová schopnost prostě je tam. Breaking change ji potřebuje, protože alternativou je, že se to volající dozví z chyby. Verzování každého vydání, včetně aditivních, učí volající, že verze jsou šum, a přestanou číst důležitá oznámení.

Praktický test je stejný jako v článku o breaking changes: pokud se volající, který se spoléhal jen na dokumentované chování, musí něco změnit, aby dál fungoval, změna potřebuje verzi. Pokud ne, vydejte ji pod aktuální verzí a napište záznam changelogu.

Jaké schéma verzování API by se mělo použít?

Použijte schéma, které vaši volající nejsnáze uvidí a nastaví, což je pro většinu veřejných API verze v cestě URL nebo datovaná hlavička verze. Čtyři běžná schémata se liší méně ve schopnostech než v tom, co požadují od volajícího, a to je správný základ pro výběr.

Cesta URL je nejviditelnější a nejméně flexibilní. Každý volající vidí, v jaké je verzi, čtením řádku logu, a skok verze je najdi-a-nahraď. Cena: celý povrch se pohne najednou, nemůžete změnit kontrakt jednoho endpointu bez vyražení nové verze pro všechny, takže verze cesty bývají vzácné a velké.

Hlavička verze udržuje URL stabilní a nechává server vybrat výchozí pro volající, kteří nic neposílají, tak funguje verzování REST API GitHubu: verze pojmenovaná podle data v X-GitHub-Api-Version, s nejstarší podporovanou verzí jako výchozí, aby se neverzovaní volající nerozbili. Cena: verze je v URL neviditelná a snadno se na ni v novém klientovi zapomene.

Datovaná verze účtu je schéma hlavičky plus jedno rozšíření: verze je uložena proti účtu, takže každý požadavek ji dostane, aniž by cokoli poslal. Verzování API Stripe upevňuje každý účet na verzi, se kterou byl vytvořen, a nechává požadavek to přepsat Stripe-Version. Toto je schéma nejpřívětivější k volajícímu a nejvíc práce na provoz, protože server musí překládat mezi každou podporovanou verzí a aktuální.

Parametr dotazu a typ média oba fungují a oba propadnou test viditelnosti různými způsoby: parametr dotazu se snadno ztratí při stavbě URL, a verze typu média je neviditelná pro téměř jakýkoli nástroj, kterým by volající ladil. Datové schéma Stripe je nejznámějším příkladem přístupu podle data a jak Stripe verzuje své API ho prochází.

Jak se verzování API dělá v praxi?

V praxi je verze pojmenovaná sada chování, a server mapuje každý požadavek na jednu z nich. Kroky jsou stejné bez ohledu na to, které schéma nese jméno.

1. Pojmenovávejte verze podle data nebo celého čísla, ne podle sémantické verze. Webové API není balíček. Volající nemohou upevnit minor verzi URL, takže v2 nebo 2026-08-26 říká všechno, co volající potřebuje, a sémantické verzování implikuje slib kompatibility, který schéma nemůže dodržet.
2. Udržujte verzi mimo cesty kódu, kterým je lhostejná. Verze by měla vybírat překladovou vrstvu na okraji, ne rozdvojovat obchodní logiku. Dvě plné kopie kódové základny jsou způsob, jak verze skončí neudržovaná.
3. Dejte každé verzi výchozí a dokument. Volající, kteří neposílají verzi, dostávají nejstarší podporovanou, nikdy nejnovější, aby se neupevněný klient nerozbil v den vydání. Každá verze má stránku, která říká, co se změnilo oproti předchozí.
4. Nastavte okno podpory a zveřejněte ho. Pokyny Googlu k verzování, AIP-185, žádají přiměřené, dobře komunikované přechodné období a doporučují 180 dní dokonce i pro beta funkce. Vyberte okno, zapište ho, a uplatňujte bez opětovného vyjednávání u každé verze.
5. Vyřazujte verze tak, jak vyřazujete endpointy. Verze, která překročila své okno, dostane stejné zacházení jako jakékoli deprekované API: oznámení, hlavičku Sunset (RFC 8594) v každé odpovědi, připomínku v polovině cesty zbývajícím volajícím, a datum odstranění, které se dodržuje.

Co jsou v1 a v2 v REST API?

v1 a v2 jsou jména pro dva kontrakty, které stejný server podporuje současně. v2 existuje, protože něco v v1 nešlo změnit bez rozbití jejích volajících, takže změna šla do nového kontraktu, a starý dál fungoval. Čísla neimplikují, že v2 je kompletní nebo že v1 je mrtvá; oba jsou pravdivé, jen pokud to říká dokumentace. v3, která se objevuje každé čtvrtletí, je znamení, že se verzují aditivní změny, nebo že kontrakt nikdy nebyl navržen tak, aby absorboval změnu.

To je model verzování přes URL cestu, kde číslo verze je segment, který volající vytáčí. gRPC služby obvykle řeší stejný problém jinak: verze žije v jméně balíčku uvnitř samotného souboru .proto. gRPC a Protobuf rozebírá ten rozdíl a to, proč se tam kompatibilita na drátě definuje čísly polí, ne tvarem URL.

Co by měla oznamovat změna verze?

Změna verze by měla oznamovat, co se rozbíjí, koho se to týká, jak migrovat, a jak dlouho předchozí verze dál funguje. Záznam má stejnou formu jako jakýkoli jiný záznam o breaking change, plus řádek oznamující okno podpory. Zde jeden pro API verzované hlavičkou:

Verze API 2026-11-01 je dostupná. Verze 2025-06-15 je podporována do 1. listopadu 2027. Nové v 2026-11-01: GET /invoices vrací amount v nejmenších jednotkách jako celé číslo místo desetinného řetězce, a deprekované pole customer_name se odstraňuje ve prospěch objektu customer. Týká se volajících na 2025-06-15, kteří parsují amount jako řetězec, což je výchozí pro neupevněné klienty vytvořené před červnem 2025. Migrace: parsujte amount jako celé číslo a čtěte jméno z customer.name. Upevněte X-Api-Version: 2026-11-01, až budete připraveni. Nic se nemění pro volající, kteří verzi neupevňují.

Poslední věta je ta, která umožňuje většině čtenářek přestat číst, a patří do každého oznámení verze. Stránka příklady changelogu obsahuje záznamy od API, která takto verzují, a rozdíl mezi dobrými a zbytkem je většinou právě v té poslední větě.

Kdo je informován, když se verze změní?

Všichni na staré verzi, individuálně, a changelog pro všechny ostatní. Změna verze je jediný případ, kdy «napsali jsme o tom příspěvek» zaručeně mine přesně ty volající, na kterých záleží: ty, kteří upevnili verzi před dvěma lety a od té doby nečetli poznámky k vydání. Data o používání odpovídají, kdo to jsou; oznámení je musí zasáhnout tam, kde je jejich kód, v hlavičkách odpovědi a ve zprávě vlastnici účtu.

Ve smyčce, kterou provádíme, se záznam oznamující verzi sestavuje z pull requestu, který ji vydává, revizuje ho člověk, a zveřejňuje se na kanálu a widgetu, kde ho verzovaný klient může přečíst jako JSON. Kdokoli, jehož zpětná vazba z widgetu žádala o tu změnu nebo hlásila chybu, kterou řeší, a stala se GitHub issue, které ten pull request uzavírá, je informován v tom issue, jakmile záznam jde na živo. Mechanismus je stejný jako u jakéhokoli záznamu; skok verze je jen záznam s nejvyšší sázkou.

FAQ

Měla by každá změna API dostat novou verzi? Ne. Jen breaking changes. Aditivní změny se vydávají pod aktuální verzí se záznamem changelogu. Verzování aditivních změn trénuje volající, aby ignorovali verze.

Je verzování přes URL lepší než přes hlavičku? Verzování přes URL je snazší vidět pro volající a těžší pro vás postupně vyvíjet; verzování přes hlavičku je opačně. Pro veřejné API s mnoha malými klienty verzování přes URL selhává méně často. Pro velké API s překladovou vrstvou se datovaná verze přes hlavičku škáluje lépe.

Kolik verzí by mělo být podporováno současně? Tak málo, kolik dovoluje vaše okno podpory, a nikdy neomezené množství. Dvě nebo tři souběžné verze jsou normální; víc obvykle znamená, že verze nejsou vyřazovány.

Co by měly dostávat neverzované požadavky? Nejstarší podporovanou verzi, aby existující neupevnění klienti dál fungovali, s hlavičkou odpovědi, která jim řekne, kterou verzi dostali.

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, Příklady changelogu