API se téměř vždy vyvíjí. Přibývají pole, mění se pravidla a některé klienty nelze aktualizovat společně se serverem. JSON umožní přidat vlastnost velmi snadno, ale kompatibilitu nezaručí. Dlouhověké rozhraní potřebuje stabilní význam, předvídatelná pravidla evoluce a měření, které ukazuje, jaké části smlouvy se stále používají.

Význam je důležitější než syntaktický typ

String může zůstat stringem a přesto rozbít klienta, pokud změní význam. Status active nemá potichu označovat jinou fázi a cena nesmí bez nové smlouvy začít obsahovat daň.

Jednotky, časové zóny a null sémantika patří do dokumentace. Nový koncept obvykle potřebuje nové pole a kontrolovanou migraci.

Aditivní změna bývá nejbezpečnější

Nová volitelná vlastnost odpovědi nevadí robustnímu klientu, který ignoruje neznámá pole. Odstranění, přejmenování, změna typu a nové povinné request pole jsou typicky breaking changes.

Také nový enum člen může rozbít uzavřený switch. SDK má nabídnout viditelný fallback pro neznámou hodnotu, pokud se seznam smí rozšiřovat.

Chybějící, null a prázdné potřebují pravidla

U částečné aktualizace může nepřítomnost znamenat „ponechat“, null „vymazat“ a prázdný string „uložit prázdnou hodnotu“. Bez jasné definice klient nechtěně ztratí data nebo je nedokáže odstranit.

Pro složité změny může být explicitní operations formát srozumitelnější než objekt s více významy každého null.

Odpovědi mají držet stejný tvar

Seznam nemá být objektem pro jeden prvek a polem pro více. ID nemá jednou cestovat jako číslo a jindy jako string. Každá výjimka vytváří podmínku ve všech klientech.

Prázdná kolekce se obvykle vrací jako prázdné pole nebo objekt, nikoli null. Konzistence zjednodušuje generované i ruční klienty.

Chyby jsou veřejnou částí smlouvy

Lidský text není stabilní strojové API. Klient potřebuje trvalý error code, vhodný HTTP status a strukturované detaily validace. Text lze potom přeložit nebo zpřesnit.

Stack trace, SQL a secrets do odpovědi nepatří. Request ID propojí bezpečný externí výsledek s interní diagnostikou.

Paginace musí fungovat v měnících se datech

Offset je jednoduchý, ale paralelní inserty způsobují přeskočení a duplikáty. Cursor navázaný na stabilní řazení lépe funguje nad aktivní sadou. Klient jej má považovat za opaque.

Řazení potřebuje tie-breaker. Samotný timestamp nestačí, pokud má více záznamů stejnou hodnotu.

Verzování přináší provozní náklady

Nová hlavní verze dovolí breaking změny, ale zdvojuje dokumentaci, testy a podporu. Pokud verze vznikne kvůli každému rozšíření, varianty rostou rychleji, než je tým dokáže vypnout.

Aditivní evoluce má zůstat výchozí cestou. Skutečný break potřebuje termín, usage metrics a migrační návod.

Request může být přísnější než response

Klient často toleruje nová pole odpovědi. Server může neznámá request pole odmítat, aby odhalil překlepy a chybná očekávání při zápisu. Tato asymetrie podporuje evoluci i bezpečnost.

Proxy zachovávající cizí data může potřebovat jinou politiku. Chování má vycházet z vlastnictví dat, ne z náhodného defaultu serializeru.

Idempotency dělá retry bezpečnější

Po timeoutu klient neví, zda objednávka vznikla. Idempotency-Key umožní zopakovat stejný záměr bez druhého efektu. Server spojí klíč, fingerprint requestu a výsledek.

Stejný klíč s jiným body má skončit konfliktem. Nové ID při každém retry popisuje novou operaci a problém neřeší.

Schema má být spustitelným zdrojem pravdy

OpenAPI nebo JSON Schema popisuje typy, povinná pole, formáty a limity. Největší hodnotu má, když stejná definice napájí validaci, dokumentaci a contract tests.

Příklady mají obsahovat prázdné seznamy, null, velké ID, neznámý enum a chyby. Ideální happy path nestačí pro robustní integraci.

Consumer testy ukazují reálné závislosti

Server může splnit schema a přesto rozbít důležitého klienta, který se opírá o nezdokumentované chování. Consumer-driven contracts takové předpoklady odhalí.

Nemají ale zmrazit pořadí JSON vlastností nebo whitespace. Test chrání význam, ne náhodný výstup knihovny.

Cache musí respektovat verzi a oprávnění

Po změně struktury mohou CDN a aplikační cache ještě vracet staré objekty. Cache key má zahrnovat verzi a parametry ovlivňující body i správný authorization context.

ETag a conditional requests snižují přenos. Během migrace musí být jasné, zda nová aplikace umí bezpečně číst starou cache.

Odstranění vyžaduje důkaz o migraci

Před smazáním pole je potřeba znát používané API keys, SDK verze a klienty. Usage metrics a komunikace snižují nejistotu. U veřejného API může být přechod dlouhý.

Deprecated funkce má do konce fungovat správně. Úmyslné zhoršování vytváří náhodné incidenty místo řízené změny.

Observability má sledovat verze a chybné předpoklady

Metriky mohou seskupovat neznámá request pole, odmítnuté enum hodnoty, používané verze SDK a deprecated endpoints. Tím odhalí klienta, který dokumentaci nepochopil, ještě před vypnutím staré funkce.

Payload není nutné celý logovat. Stačí bezpečný error code, schema path, client identity a request ID. Diagnostika zůstane užitečná bez kopírování osobních dat.

Kontrakty potřebují vlastní release proces

Změna schema má review, changelog a test kompatibility podobně jako změna databáze. Ideálně se nejprve nasadí tolerantní reader, poté nový writer a až nakonec odstraní starý tvar.

Toto pořadí snižuje riziko při rolling deploy, kdy současně běží několik verzí serveru a workerů.

Odolnost je také organizační proces

Review má kontrolovat kompatibilitu, privacy, limity a error model. Changelog i migration guide musí vzniknout před změnou chování. Vlastník smlouvy odpovídá za celý přechod.

Dobré API je předvídatelné: stará pole drží význam, rozšíření jsou aditivní, breaks mají verzi a odstranění se řídí skutečným využitím.