Verzování API a zpětná kompatibilita v e-commerce

Integrace funguje tři roky bez zásahu. Pak jednoho rána přestanou chodit objednávky do ERP. Nikdo nic neměnil. Změnila se ale druhá strana: platforma ukončila podporu staré verze API nebo přejmenovala pole, na které se integrace spoléhala. Upozornění přitom přišlo měsíce dopředu. Jen ho nikdo nečetl.

Verzování API je způsob, jak měnit rozhraní, aniž by se rozbilo všechno, co na něm stojí. V článku vysvětlujeme, co je zpětně nekompatibilní změna, jak verzování řeší platformy, se kterými pracujeme, a jak postavit integraci e-shopu tak, aby změny přežila.

Co je zpětně nekompatibilní změna

Zpětně kompatibilní změna nerozbije stávající klienty. Nekompatibilní ano. Rozdíl není vždy intuitivní:

Poslední řádek je v e-commerce častý zdroj problémů. Platforma přidá nový stav objednávky nebo nový typ dopravy. API se formálně nerozbilo, ale integrace do ERP neví, co s novou hodnotou dělat, a objednávku přeskočí.

Jak se API verzují

Existuje několik způsobů, jak verzi API označit:

• Verze v URL, například /wc/v3/orders u WooCommerce. Je hned vidět, kterou verzi voláte.
• Verze podle data, například 2026-07 u Shopify nebo 2025-01-27.acacia u Stripe. Z názvu je jasné, jak je verze stará.
• Verze v hlavičce požadavku, například Stripe-Version. URL zůstává stejná.
• Bez explicitní verze, s ohlašováním změn. API se vyvíjí průběžně, nekompatibilní změny se oznamují předem a zastaralé části se označí v odpovědi.

U vlastních knihoven a služeb se často používá sémantické verzování (SemVer 2.0.0) ve tvaru MAJOR.MINOR.PATCH. Zvýšení prvního čísla znamená nekompatibilní změnu, druhého novou zpětně kompatibilní funkci, třetího opravu chyby. Když vidíte skok z 2.x na 3.0, víte, že je potřeba číst poznámky k vydání.

Jak to dělají platformy, se kterými pracujeme

Pravidla se liší platformu od platformy. Stav k 9/2026 podle oficiální dokumentace:

Shopify navíc vrací v každé odpovědi hlavičku X-Shopify-API-Version. Pokud se liší od verze, kterou jste požadovali, voláte verzi, která už není dostupná. Hlavička X-Shopify-API-Deprecated-Reason pak říká, jaké zastaralé části API jste použili.

Obecně k tomu existují i standardy. RFC 9745 definuje hlavičku Deprecation, která oznamuje, že zdroj je nebo bude zastaralý. RFC 8594 definuje hlavičku Sunset s datem, kdy zdroj pravděpodobně přestane odpovídat.

Jak postavit integraci, která změny přežije

Změnám API se vyhnout nedá. Dá se ale omezit, kolik práce každá z nich způsobí. Principy, které při stavbě integrací dodržujeme:

1. Vždy volejte konkrétní verzi. Nespoléhejte na výchozí nebo „nejnovější“ verzi. Integrace se pak nezmění pod rukama sama od sebe.
2. Buďte tolerantní ke změnám. Neznámá pole ignorujte. Nespoléhejte na pořadí atributů. Na neznámou hodnotu výčtu reagujte bezpečně, například odložením záznamu k ruční kontrole místo pádu celé synchronizace.
3. Oddělte volání API od byznys logiky. Když je práce s API soustředěná v jedné vrstvě (adaptér nebo middleware), změna verze znamená úpravu jednoho místa, ne celé aplikace.
4. Logujte hlavičky o zastarání. X-Shoptet-Deprecated, Sunset, Deprecation, X-Shopify-API-Deprecated-Reason. Každý výskyt je úkol do backlogu s termínem.
5. Mějte testy proti nové verzi. Před přechodem spusťte integraci proti nové verzi API na testovacím prostředí. Postup popisujeme v článku Testování integrací před nasazením do provozu.
6. Sledujte changelog. Nejlépe s evidencí, které endpointy a webhooky integrace používá. Proč je taková evidence důležitá, rozebíráme v článku Dokumentace API.

U GraphQL je situace trochu jiná. Klient si sám říká o pole, která potřebuje, takže přidání nových polí ho nikdy neovlivní. Odebrání pole ale ano, a proto i GraphQL API jako Shopify verzují a pole před odebráním označují jako zastaralá. Rozdíly mezi přístupy shrnuje článek REST vs. GraphQL API pro e-commerce integrace.

Když verzujete vlastní API

Pokud stavíte vlastní REST API, například pro B2B odběratele nebo mobilní aplikaci, platí stejná pravidla z druhé strany:

• Nekompatibilní změnu dělejte jen s novou verzí. Starou nechte běžet po předem oznámenou dobu.
• Termín konce podpory oznamte předem a zároveň ho posílejte v hlavičkách Deprecation a Sunset.
• Veďte changelog. Každá změna, datum, dopad na klienty.
• Sledujte, kdo starou verzi ještě volá. Vypnout ji můžete, až když provoz opravdu klesne.

Mobilní aplikace je zvlášť citlivý případ. Nemůžete donutit všechny uživatele aktualizovat, takže stará verze API musí vydržet déle než u serverových integrací.

Jak na to prakticky

Rychlá kontrola vašich integrací:

• Víte u každé integrace, jakou verzi API volá?
• Jsou některá napojení postavená na Legacy REST API WooCommerce nebo na verzi Shopify, která se blíží konci podpory?
• Loguje integrace hlavičky o zastarání a někdo je čte?
• Sleduje někdo changelog platformy a porovnává ho s tím, co integrace používá?
• Máte testovací prostředí, kde jde novou verzi API vyzkoušet před nasazením?

Pokud jste u víc než jedné otázky odpověděli „nevím“, je vhodná doba na revizi. Chyba se jinak projeví až v den, kdy platforma starou verzi vypne.

Kdy nám zavolat

Pokud vám platforma ohlásila konec podpory verze API, kterou vaše integrace používá, nebo nevíte, na čem vaše napojení stojí, projdeme je a připravíme přechod. Integrace stavíme tak, aby změny API šly zvládnout úpravou jednoho místa, v rámci služby integrace. Vlastní API navrhujeme včetně verzování a dokumentace v rámci služby API a microservices. Kontakt: info@prevedshop.cz, +420 723 000 173.