Praktický návod

Jak navrhnout verzování API

Novou verzi přidej až pro změnu, kterou stávající klient nedokáže bezpečně přijmout.

25 minut · API

Nejdřív stručně

Verzuješ kontrakt, ne nasazení

API je kontrakt mezi poskytovatelem a klientem. Zpětně kompatibilní změna dovolí starému klientovi fungovat dál; nekompatibilní změna vyžaduje nový kontrakt a plán migrace.

Endpoint nemusí dostat novou verzi při každém vydání serveru. Hlavní verze odděluj pouze tehdy, když měníš význam, strukturu nebo chování způsobem, který by existujícího klienta rozbil.

Připrav si

Co budeš potřebovat

Verzování funguje jen tehdy, když znáš současný kontrakt a jeho skutečné uživatele.

Seznam klientů API, jejich vlastníků a verzí, které dnes používají.
Strojově čitelný popis současného kontraktu, například OpenAPI, a integrační nebo kontraktní testy.
Písemnou definici zpětně kompatibilní a nekompatibilní změny pro váš tým.
Způsob měření provozu podle verze a komunikační kanál pro oznámení migrace a ukončení podpory.

Kroky 1 až 3

Zaveď verze jako řízenou změnu kontraktu

Nejdřív nastav pravidla, potom způsob adresování a nakonec životní cyklus staré verze.

1. Definuj, co je nekompatibilní změna

Za nekompatibilní považuj odstranění nebo přejmenování pole, změnu jeho typu či významu, zpřísnění povinného vstupu a změnu autentizace nebo chybového chování.
Přidání volitelného pole bývá kompatibilní jen tehdy, když klienti tolerují neznámá pole. Tuto vlastnost ověř testem, nepředpokládej ji.
Opravy chyb posuzuj podle pozorovatelného chování. Pokud na starém chování klient závisí, může i oprava vyžadovat novou verzi.
Pravidla zapiš do dokumentace repozitáře a kontroluj změnu kontraktu při code review a v CI.

Oficiální specifikace OpenAPI

2. Vyber jeden způsob adresování verze

Pro veřejné HTTP API je jednoduchá hlavní verze v cestě, například /api/v1/orders. Je viditelná v routách, logu, dokumentaci i cache.
Verze v hlavičce nebo media type může zachovat stejné URL, ale hůř se zkouší v prohlížeči a musí být správně zahrnuta do cache klíče pomocí Vary.
Zvol jeden způsob pro celé API a nemíchej ho mezi endpointy. Verzi neposílej současně v cestě i hlavičce jako dva nezávislé zdroje pravdy.
V URL udržuj jen hlavní verzi. Interní release aplikace může pokračovat vlastním tempem bez změny veřejného kontraktu.

php bin/console debug:router

RFC 9110: sémantika HTTP

3. Provozuj migraci, ne trvalou kopii

Odděl transportní adaptéry v1 a v2, ale sdílej aplikační use-case a doménová pravidla. Nekopíruj celý systém kvůli jinému tvaru odpovědi.
Pro novou verzi publikuj přesný rozdíl, příklady, migrační postup a termín ukončení staré verze. Klient musí vědět, co upravit a do kdy.
Starou verzi během přechodu opravuj a sleduj její provoz podle identifikovaného klienta. Nepřestávej ji testovat, dokud ji skutečně nevypneš.
Ukončení oznam opakovaně a s předstihem. Je-li to vhodné, přidej standardní hlavičku Sunset a odkaz na migrační dokumentaci.

RFC 8594: hlavička Sunset

Krok 4

Ověř obě verze jako samostatné kontrakty

Po dobu migrace musí každá podporovaná verze projít vlastními testy.

Zkontroluj routy obou verzí

Každý veřejný endpoint musí být dostupný jen pod zamýšlenou verzí a HTTP metodou.
```
php bin/console debug:router | grep '/api/v'
```
Spusť kontraktní testy v1 i v2

V1 musí zachovat starý tvar a význam, zatímco v2 ověřuje nový kontrakt. Sdílená business pravidla testuj společně.
```
php bin/phpunit tests/Contract/Api
```
Ověř oznámení ukončení podpory

U staré verze zkontroluj hlavičky a odkaz na migrační návod, ale pouze pokud už byl termín veřejně oznámen.
```
curl -i https://api.example.test/api/v1/orders/42
```

Když to zlobí

Nejčastější chyby

API dostává novou verzi při každém release

Odděl interní verzi nasazení od veřejné hlavní verze kontraktu. Kompatibilní pole a nové endpointy přidávej do současné verze.

V1 a v2 obsahují dvě kopie business logiky

Přesuň rozdíl do vstupních a výstupních adaptérů. Aplikační operace a doménová pravidla sdílej, pokud se jejich význam skutečně nezměnil.

Kompatibilní změna rozbila starého klienta

Klient nejspíš odmítá neznámá pole nebo závisí na nezapsaném chování. Přidej jeho případ do kontraktních testů a pravidla kompatibility zpřesni.

php bin/phpunit tests/Contract/Api/V1

Starou verzi nelze nikdy vypnout

Měř použití podle klienta, přiřaď vlastníka migrace a stanov konkrétní termín. Bez kontaktů, telemetrie a komunikačního plánu není ukončení podpory řiditelné.

Hotovo

Verze API mají jasný životní cyklus.

API teď rozlišuje kompatibilní rozšíření od změn vyžadujících nový kontrakt. Další hlavní verzi otevři jen s migračním plánem, telemetrií a termínem ukončení té staré.

Přečíst API ve slovníku Všechny návody