Definujte, co je veřejný kontrakt, přidávejte nové nepovinné možnosti kompatibilně, význam existujících polí neměňte potichu a při nekompatibilní změně vytvořte jasnou verzi s migračním návodem, termínem podpory, kontraktovými testy a monitoringem aktivních klientů.
Verzování API řeší situaci, kdy se potřeby poskytovatele a klientů vyvíjejí odlišným tempem. Změna názvu pole, významu stavu nebo povinnosti může poškodit integraci i tehdy, když endpoint stále odpovídá. Bez jasné politiky se tým bojí kontrakt zlepšit, nebo naopak pravidelně překvapuje klienty nekompatibilní úpravou.
Nejlepší nová verze je často ta, kterou není třeba vytvářet, protože změnu lze přidat kompatibilně. Když nekompatibilita dává smysl, potřebuje přechodné období, dokumentaci, testovací prostředí a znalost aktivních konzumentů. Verze není jen číslo v URL; zahrnuje schéma, chování, chyby a provozní očekávání.
Vymezte kontrakt a kompatibilitu
Kontrakt zahrnuje cesty, metody, pole, typy, povinnost, enumy, stavové kódy, pořadí a význam operací. V praxi k němu patří i limity, stránkování, autentizace a časové chování. Změna interního kódu není změnou API, dokud nemění pozorovatelné očekávání klienta. Tento rozsah sepište a udržujte na jednom autoritativním místě.
Zpětná kompatibilita znamená, že existující správně napsaný klient pokračuje bez vynucené změny. Přidání nepovinného pole bývá kompatibilní jen tehdy, když klient toleruje neznámé hodnoty podle kontraktu. Přidání nové hodnoty enumu může rozbít uzavřený přepínač. Posuzujte skutečné chování, nikoli jen syntaktické schéma.
Upřednostněte kompatibilní evoluci
Nové pole nejprve přidejte jako nepovinné, naplňte je a umožněte klientům přechod. Staré pole ponechte po dohodnuté období a sledujte jeho používání. Neměňte jednotku, časové pásmo ani význam bez nového názvu nebo verze. Server má rozumně tolerovat nepodstatné rozšíření požadavku, pokud to bezpečnost dovolí.
Při změně chování zvažte novou explicitní schopnost nebo parametr místo skrytého přepnutí. Výchozí hodnota musí zachovat očekávání stávajících klientů. Dočasná dvojí implementace zvyšuje náročnost údržby, proto potřebuje vlastníka a datum odstranění. Kompatibilita není důvodem udržovat vše navždy bez plánu.
- nepovinné přidání před odstraněním
- nový název při změně významu
- bezpečná výchozí hodnota
- sledovaný přechod s datem ukončení
Zaveďte verzi na vhodné hranici
Verzi lze vyjádřit v URL, hlavičce, schématu události nebo jiném podporovaném mechanismu. Zvolte jeden konzistentní přístup podle platformy a způsobu distribuce. Nezavádějte novou hlavní verzi kvůli každé drobnosti. Má reprezentovat soubor nekompatibilních očekávání, který klient dokáže vědomě zvolit a otestovat.
Webhook a dávkový export potřebují vlastní verzi payloadu, i když používají stejné doménové pojmy jako REST API. Verzi ukládejte s událostí, aby ji příjemce dokázal zpracovat i později. Dokumentace uvádí rozdíly, příklady migrace a známá omezení. Staré a nové příklady nesmí být bez označení promíchané.
Oznamujte ukončení podpory a podpořte migraci
Před ukončením zjistěte aktivní klienty a kontakty na jejich vlastníky. Oznámení má uvést důvod, náhradu, rozdíly, testovací možnosti, termíny a kanál podpory. U kritického partnera nestačí jedna poznámka v seznamu změn. Přechodné období určete podle rizika a smluv, nikoli podle pohodlí jednoho týmu.
Poskytněte migrační návod a testovací scénáře. Pokud lze automaticky zjistit staré používání, zobrazte varování v portálu nebo v odpovědi bez úniku informací. Před vypnutím ověřte pokles aktivity a eskalujte neznámé konzumenty. Po termínu odstraňte starý kód kontrolovaně a sledujte neočekávané chyby.
Automatizujte kontraktové testy a sledování
Schéma validujte v CI a porovnávejte s poslední vydanou verzí. Testy poskytovatele ověří příklady a pravidla, spotřebitelské kontrakty zachytí důležitá očekávání skutečných klientů. Nepovažujte je za úplnou náhradu integrace; význam dat a provozní limity vyžadují end-to-end scénáře v bezpečném prostředí.
V produkci sledujte verzi, klienta, chyby validace a používání deprekovaných polí bez nadměrného profilování. Změnu nasazujte postupně a připravte návrat. Každý incident aktualizuje politiku a testy. Dobře řízené verzování umožňuje API růst, aniž by se každé zlepšení změnilo v koordinovaný výpadek.
- automatické porovnání veřejného schématu vydání
- spotřebitelská očekávání kritických integračních partnerů
- test kompatibility historických vzorových požadavků
- monitoring klientů používajících starou verzi
- ověření migračního návodu v testovacím prostředí
- jasný vlastník termínu ukončení staré verze
- kontrolované odstranění nevyužívaného kompatibilního kódu
Časté dotazy
Musí být verze API v URL?
Ne. Může být v URL, hlavičce nebo jiném dohodnutém mechanismu. Důležitá je konzistence, jasná volba klienta, dokumentace a schopnost přechod provozně zvládnout.
Je přidání nového pole vždy kompatibilní?
Ne vždy. Klient může odmítat neznámá pole nebo nové enumy. Kontrakt musí určit toleranci a změnu je třeba ověřit testy a chováním aktivních konzumentů.
Jak dlouho podporovat starou verzi?
Podle smluv, počtu klientů, rizika a náročnosti migrace. Stanovte konkrétní plán, komunikujte ho předem a ověřte používání; neurčitá podpora navždy brzdí bezpečnou údržbu.
Zdroje a další čtení
Adam Antoni vyvíja weby, aplikácie a softvér na mieru. Prepája firemné systémy, automatizuje procesy a vytvára AI agentov. Pôsobí v Spišskej Novej Vsi a spolupracuje s firmami na celom Slovensku.
