Verzování API

Verzování API a backward kompatibilita: proč na nich záleží

Ve světě API managementu je verzování a zajištění zpětné kompatibility klíčové pro stabilitu ekosystému, řízené nasazování změn a důvěru spotřebitelů API. Dobře navržené verzování snižuje náklady na údržbu, minimalizuje rizika při releasu a zjednodušuje plánování rozvoje produktů.

Základní typy verzování API

• Verze v cestě (URI path) – např. /v1/objednavky, /v2/objednavky. Jasně čitelné, dobře směrovatelné přes API Gateway, snadná koexistence více verzí.
• Verze v hlavičce – např. Accept: application/vnd.acme.orders+json;version=2. Vhodné pro content negotiation, čisté URI, ale náročnější pro debugging.
• Verze v parametru dotazu – např. /orders?version=2. Jednoduchá implementace, ale verze není součástí identifikace zdroje.
• Mediální typy – např. application/vnd.firma.zbozi.v3+json. Vysoce explicitní, dobře se kombinuje s evolučními schématy.

V praxi se často volí verze v cestě pro veřejná API a verze v hlavičkách pro interní či partnerká API s vyšší vyspělostí klientů.

SemVer a verze API vs. verze schématu

Semantické verzování (SemVer) definuje pravidla typu MAJOR.MINOR.PATCH. U API je užitečné rozlišit:

• Verze rozhraní (API) – mění se při breaking změnách, např. v1 → v2.
• Verze schématu (např. OpenAPI/JSON Schema) – může se vyvíjet jemněji (minor/patch) v rámci jedné hlavní verze API.

Ne každá změna schématu vyžaduje změnu hlavní verze API. Additive změny (přidání volitelných polí) jsou typicky backward kompatibilní, zatímco removal/rename polí, změna významu či povinnosti pole jsou breaking a měly by vést k nové major verzi.

Co je to backward kompatibilita (BC)

Backward kompatibilita znamená, že existující klienti mohou nadále používat API bez úprav po provedení změn na straně poskytovatele. Prakticky to znamená zachovat:

• Stálé kontrakty – nezměněné názvy a datové typy existujících polí a endpointů.
• Predikovatelné chování – stejné status kódy, stejné významy výjimek, stejné defaulty.
• Toleranci – klienti by měli ignorovat neznámá (nová) pole; API by mělo přijímat starší formy požadavků.

Matrix kompatibilních a nekompatibilních změn

• Kompatibilní (non-breaking): přidání volitelného pole, přidání nového endpointu, přidání nové hodnoty enumu s jasným defaultem na straně klienta, navýšení limitu stránkování, rozšíření filtrů.
• Nekompatibilní (breaking): odstranění pole, změna datového typu, přejmenování pole, změna semantics (např. jednotek), změna povinnosti pole na povinné, zpřísnění validace bez přechodného období.

Verzování REST vs. GraphQL vs. gRPC vs. event-driven API

• REST: tradičně path/headers; pro BC je klíčové HATEOAS (odkazy), stabilní zdrojové reprezentace a tolerující klienti.
• GraphQL: preferuje evoluční přístup bez major verzí – pole se označí jako deprecated, přidávají se nová pole, stará se po období odstraní. Major verze se řeší výjimečně (nový endpoint/schéma).
• gRPC: využívá Protocol Buffers s explicitními číselnými tagy polí. Dodržování pravidel (neznovupoužívat tagy, pouze přidávat volitelná pole) umožňuje BC bez změny služby.
• Event-driven / asynchronní API: verze zprávy v event.type či v payloadu; schéma validace (např. Avro/JSON Schema) a schema registry. Spotřebitelé musí být schopni ignorovat neznámé atributy.

Strategie zavádění nových verzí

1. Paralelní provoz – v1 a v2 běží souběžně. API Gateway směruje podle pravidel (path/header). Umožní postupnou migraci.
2. Canary/Dark launch – provoz omezené části provozu na v2, zbytek na v1; sledování metrik a chybovosti před plným přepnutím.
3. Feature flagy – aktivace nových funkcí per klient nebo per token; vhodné pro řízené testování.
4. Shadow traffic – duplikace požadavků do v2 jen na měření a validaci odpovědí, bez dopadu na klienty.

Politika deprecace a komunikace se spotřebiteli

• Deprecation policy: definujte minimální podporu (např. 12 měsíců od oznámení) a pravidla pro odstranění.
• Hlavičky: používejte Deprecation s datem, Sunset s konkrétním termínem, a Link: <...>; rel="deprecation" na migrační dokumentaci.
• Release notes & changelog: srozumitelné příklady před/po, vliv na klienty, časová osa.
• Notifikace: e-maily, status page, webhooks o změnách, deprecation bannery v developer portálu.

Role API Gateway při verzování

API Gateway centralizuje směrování podle verze (path/header), aplikuje traffic shaping, poskytuje A/B směrování, limitování na úrovni verze, authN/authZ pro jednotlivé verze a uniformní observabilitu (tracing/logging/metrics) včetně tagu verze.

Kontrakty, testování a kvalita

• Kontraktační zdroj pravdy – OpenAPI/AsyncAPI/Protobuf; verzujte kontrakty stejně přísně jako kód.
• Consumer-Driven Contracts (CDC) – např. Pact; validace očekávání reálných klientů proti poskytovateli.
• Golden tests – fixní příklady požadavků/odpovědí pro každou verzi.
• Validace schématu – servery i klienti validují proti správné verzi; CI blokuje breaking změny bez zvednutí major verze.

Navrhové vzory pro evoluci bez přerušení

• Přidávání volitelných polí – zachovejte defaulty a backward kompatibilitu klientů.
• Aliasování a postupná migrace – staré pole zůstává, nové pole je dostupné; dokumentujte preferované pole.
• Verzované embedované objekty – pole může mít vlastní verzi, např. address_v2 v rámci customer.
• Idempotence – klíčová při změnách procesních toků; verze mohou mít jiné garance idempotence, což je nutné explicitně sdělit.

Verzování chyb a status kódů

Udržujte konzistentní error.code, error.type a strukturu chyb napříč verzemi. Přidání nových chyb je kompatibilní, ale změna významu stávajících nikoli. Doporučuje se correlationId pro trasovatelnost a odkaz na dokumentaci chyby.

Bezpečnost a oprávnění napříč verzemi

• Scopes per verze – tokeny mohou obsahovat claim s verzí nebo rozsahem oprávnění pro v1/v2.
• Rotace klíčů – nezávislá na verzích, ale plány rotace by měly respektovat koexistenci více verzí.
• Rate limiting & kvóty – nastavujte na úrovni verze i klienta; umožní řídit migraci a chránit staré verze.

Observabilita a produktové metriky

• Tagování verze v logách, tracích a metrikách (např. api.version=v2).
• Dashboardy – adopce verze, chybovost, latence, top klienti na v1/v2, pokrytí migrovaných endpointů.
• Alerting – prahové hodnoty odděleně pro v1 a v2 zamezí „ředění“ signálu.

Dokumentace a developer experience

• Verzované dokumentace – přepínač verze v portálu, stabilní URL pro každou major verzi.
• Embedded příklady – ukázky požadavků/odpovědí pro každou verzi; generované SDK by měla odpovídat verzi kontraktu.
• Migrační průvodci – tabulky mapování polí, checklist změn, „nejčastější pasti“.

Lifecycle řízení verze

1. Design – RFC, schválení architektem, dopadová analýza na klienty.
2. Implementace – kontrakt-první, testy, bezpečnostní review.
3. Beta – omezeným klientům, jasné SLA „best effort“.
4. GA – stabilní SLA, plná podpora.
5. Deprecation – oznámení s termíny, Sunset hlavičky, migrační materiály.
6. Retire – vypnutí, 410 Gone pro dotčené endpointy, archivace kontraktů a dat.

Verzování webhooks a zpětných volání

Webhooky musí mít vlastní verzi payloadu a podpisového formátu. Zajistěte možnost registrovat URL s preferovanou verzí (např. events/v2) a poskytujte testovací eventy pro validaci klientů před přechodem.

API design pro budoucí kompatibilitu

• Rozšiřitelná schémata – používejte objektové struktury místo plochých seznamů polí, rezervujte prostor pro budoucí rozšíření.
• Stabilní identifikátory – nepřenášejte interní ID či impl. detaily.
• Explicitní verze enumerací – dokumentujte, že klienti musí ignorovat neznámé hodnoty.
• Deterministické stránkování – cursor-based je robustnější vůči změnám než offset/limit.

Checklist: než vydáte novou verzi

• Je každá breaking změna opravdu nutná? Lze ji modelovat aditivně?
• Existuje migrační průvodce a příklady před/po?
• Je nastavena deprekační hlavička a datum sunset?
• Funguje směrování přes API Gateway pro všechny způsoby verze?
• Běží CDC/golden testy a jsou zelené?
• Metriky a logy obsahují tag verze a dashboardy jsou připravené?
• Byl proveden canary/dark launch alespoň na části provozu?
• Jsou SLA a rate limity definovány pro novou verzi?

Příklady změn a jejich klasifikace

• Přidání pole: GET /v1/orders začíná vracet volitelné discountCode. Kompatibilní.
• Změna typu: price z string na number. Nekompatibilní → v2.
• Refaktor struktury: addressLine1, addressLine2 → objekt address. Nekompatibilní → v2 s paralelní podporou starých polí po dobu deprecace.
• Zpřísnění validace: minimální délka hesla. Potenciálně breaking pro create/update – vyžaduje oznámení a přechodné období.

Organizační a procesní aspekty

• Správa katalogu verzí – centrální evidence aktivních/ukončených verzí, vlastníci, SLA, milníky.
• Governance – architektonická rada schvaluje breaking změny a harmonogramy.
• Verzování závislostí – SDK, klientské knihovny a infrastrukturní šablony musí reflektovat verze API.

Závěr

Verzování API a backward kompatibilita nejsou jen technický detail, ale produktová strategie. Správně navržené verze, jasná pravidla deprecace, silné testování kontraktů a důsledná komunikace se spotřebiteli umožní bezpečně rozvíjet API, aniž by docházelo k narušení fungování klientů. Investice do těchto praktik se vrací v nižších nákladech na podporu, vyšší spokojenosti integrátorů a rychlejším tempu inovací.