Verzování REST API: URL, hlavička nebo query, co se hodí

Verzování REST API je způsob, jakým API říká volajícímu, který kontrakt požadavek používá, aby server mohl kontrakt změnit, aniž by rozbil volající, kteří se ještě nepřesunuli. Verze může být na třech místech: v cestě URL (/v2/orders), v hlavičce požadavku (Accept: application/vnd.acme.v2+json nebo vlastní Api-Version: 2026-10-01), nebo v parametru dotazu (/orders?version=2). Cesta je nejběžnější, protože je vidět všude, hlavička je nejčistší pro URL a query string je ten, kterého většina týmů lituje. Co se hodí, závisí na tom, kdo jsou vaši volající a jak jim plánujete oznamovat změny.

Co je v1 a v2 v REST API?

v1 a v2 jsou označení dvou verzí kontraktu API: stejné zdroje dostupné na různých cestách, kde v2 může přejmenovat pole, změnit typy, zrušit endpointy nebo změnit tvar chyb, na kterých volající v1 závisejí. Požadavek na /v1/orders dostává starý tvar tak dlouho, dokud je v1 podporovaná; požadavek na /v2/orders dostane nový. Číslo je slib o kompatibilitě a právě ten slib ho dělá užitečným. Zvyšovat ho při každém vydání z něj udělá šum.

Většina API potřebuje novou hlavní verzi jen pro změnu, která rozbije existující volající. Přidání pole, nového endpointu nebo nového volitelného parametru může vyjít pod aktuální verzí, protože dobře napsaný klient ignoruje, co nezná. Kdy API verzovat a co dělat místo toho se věnuje tomu rozhodnutí; tento článek je o tom, kam verze při verzování REST API patří, jakmile jste se rozhodli ji zvýšit.

Má verzování REST API jít do URL, nebo do hlavičky?

Dejte ji do URL, pokud mezi vašimi volajícími jsou lidé, kteří píší požadavky do prohlížeče, kopírují příklady z dokumentace nebo čtou logy; dejte ji do hlavičky, pokud chcete jednu stabilní URL na zdroj a vaši volající jsou samé SDK nebo kód, který ovládáte. Cesta URL je explicitní tak, jak nic jiného: tiket na podpoře s řádkem požadavku už vám říká verzi. Hlavička se musí nastavit u každého požadavku, v odkazu je neviditelná a snadno se ztratí na proxy, a proto API verzovaná hlavičkou vždy definují výchozí verzi pro požadavky, které žádnou neposílají.

Přístup přes hlavičku má kromě úhledných URL jednu skutečnou výhodu: odděluje identitu zdroje od jeho reprezentace, což je způsob, jakým bylo HTTP navrženo. RFC 9110 popisuje vyjednávání obsahu přes Accept a typ média jako application/vnd.github.v3+json je verze vyjádřená právě takto. V praxi záleží na čistotě návrhu méně než na tom, zda si vaši volající vzpomenou hlavičku poslat.

Jak funguje verzování podle data?

Místo v1 a v2 je verzí datum a každá zásadní změna dostane nové datum. Volající upevní datum, proti kterému integroval, obvykle jednou na úrovni účtu, a to chování si drží, dokud se sám nerozhodne přejít. Takto fungují jak hlavička Stripe-Version u Stripe, tak X-GitHub-Api-Version u GitHubu.

Kompromis je v implementaci. Každá zásadní změna se stane malou překladovou vrstvou, která převádí mezi upevněným datem a aktuálním tvarem, a server je skládá na sebe: požadavek upevněný dva roky zpátky projde každou změnou od té doby. To je náročnější postavit než druhou kopii handlerů a odměňuje to API, které se mění zřídka. Týmy, které vydávají zásadní změnu každý měsíc, skončí s desítkami transformací. Verzování API Stripe se na model dívá ze strany volajícího, včetně toho, co musí nést changelog.

Proč se verzování přes query string nedoporučuje?

Protože míchá kontrakt s filtry. /orders?status=open&api-version=2 dělá z verze něco jako volitelné zpřesnění, ne věc, která rozhoduje o tvaru každého pole v odpovědi. Je to také ta, která se nejsnáz omylem ztratí, protože query stringy klientské knihovny přestavují, některé proxy je ořezávají a lidé je upravují ručně. Vlastní pokyny Microsoftu k návrhu REST API dokumentují formu s parametrem dotazu, kterou Azure používá, a ekosystém generovaných SDK kolem ní je to, co ji dělá použitelnou; bez takového nástroje dostane volající, který parametr zapomene, potichu výchozí verzi.

Co se stane se starou verzí?

Běží dál, s datem, kdy skončí. Smyslem verzování je nechat volající přejít podle vlastního harmonogramu, a to platí jen tehdy, když stará verze zůstane dostupná dost dlouho na to, aby to stihli, a když se dozví, kdy končí. Pokyny Googlu k verzování API popisují životní cyklus, který používá pro vlastní API: stabilní verze je podporována do zveřejněného data deprekace a náhrada je dostupná po celé okno deprekace.

Oznámení je část, kterou většina týmů podcení. Nová cesta nebo hlavička je užitečná jen volajícím, kteří vědí, že existuje, vědí, co se změnilo, a vědí, kdy v1 zmizí. To jsou tři fakta a každý potřebuje svůj domov: datovaný záznam v changelogu API s rozdíly na úrovni polí, oznámení o deprekaci, které uvádí datum konce, a migrační průvodce, který volajícího, jenž je stále na staré verzi, provede každou změnou. Ukončení verze API popisuje poslední krok, včetně hlavičky Sunset, díky které klient zjistí datum z každé odpovědi.

Dá se verzování REST API úplně vyhnout?

Ano, dokud je každá změna aditivní. Přidávejte pole, nikdy je neodstraňujte ani nepřejmenovávejte; přidávejte endpointy, nikdy neměňte, co vrací existující; přijímejte nové volitelné parametry, nikdy neměňte význam starého. Mnoho interních API běží roky jen na tomto pravidle a je to pravidlo, které schémata GraphQL dodržují už z návrhu. Cenou je kontrakt, který jen roste, s deprekovanými poli, která musí zůstat, protože je někdo někde stále čte.

Když aditivní změna není možná, je verze ten správný nástroj. Volba mezi cestou, hlavičkou a datem rozhoduje, co volající vidí a jak se změna oznamuje; neměnné zůstává to, že změna se musí zapsat někam, kde si ji volající přečte. U API s externími volajícími je to místo changelog a článek o breaking changes popisuje, co se za ně počítá.

FAQ

Jaký je nejlepší způsob verzování REST API? Hlavní verze v cestě URL je nejšířeji chápaná a nejhůř se v ní udělá chyba, což z ní dělá výchozí volbu pro veřejné API. Verze v hlavičce udržuje URL stabilní a hodí se API řízeným přes SDK; datovaná hlavička se hodí API, která se mění zřídka a chtějí, aby si volající chování upevnili.

Co je v1 v URL API? Je to první hlavní verze kontraktu API. Požadavkům na /v1/... je slíben tvar zdokumentovaný pro verzi 1, i poté, co existuje /v2/ s jinými poli nebo chováním.

Potřebuji novou verzi API pro každou změnu? Ne. Aditivní změny jako nová pole, endpointy a volitelné parametry mohou vyjít pod existující verzí. Novou potřebuje jen změna, která rozbije existující volající.

Jak dlouho má být stará verze API podporována? Dost dlouho na to, aby volající stihli migrovat, což je u veřejného API obvykle šest až dvanáct měsíců po zpřístupnění náhrady, s datem zveřejněným při oznámení a zopakovaným v oznámení o deprekaci.

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