Egy JSON API első verziója könnyen elegánsnak tűnik, mert a szerver és az első kliens együtt készül. A valódi kihívás később érkezik, amikor mobilalkalmazások nem frissülnek azonnal, partnerek saját integrációt futtatnak, payloadok kerülnek queue-ba, és a mezők jelentésére üzleti folyamatok épülnek. Egy átnevezés vagy típusváltás ekkor már nem belső refaktor, hanem nyilvános szerződésmódosítás.

A bővítés biztonságosabb, mint a jelentés átírása

Egy új opcionális response mezőt a régi kliens általában figyelmen kívül hagyhat. Egy szám objektummá alakítása vagy kulcs átnevezése viszont parserhibát vagy csendes félreértést okozhat.

Nagy változásnál új mezőt kell hozzáadni, egy ideig mindkettőt kiadni, mérni a használatot, majd dokumentált verzióban megszüntetni a régit.

A tolerancia iránya számít

A kliens válaszban figyelmen kívül hagyhat ismeretlen mezőket, hogy a szerver bővíthető maradjon. Rossz típust vagy hiányzó kötelező értéket azonban nem szabad elfednie, ha abból biztonsági döntés következik.

A szerver request oldalon gyakran szigorúbb. Egy elgépelést nem jó csendben kihagyni és defaulttal folytatni. A hiba mutassa meg a mező útvonalát és az elvárt típust.

A null és a hiány stabil szemantikát igényel

Részleges frissítésben a hiány jelentheti a változatlanságot, a null a törlést. Az SDK, validator és adatbázisréteg ugyanazt a szabályt használja.

Az üres tömb, objektum és string további külön állapot. Általános „falsy értékek eltávolítása” nem helyettesíti a domén döntését.

A stabil azonosító különüljön el a megjelenítéstől

A felhasználónév, slug és lokalizált cím változhat. Ha ez az egyetlen foreign key, minden átnevezés linkeket tör. Az API adjon stabil ID-t és külön prezentációs mezőket.

A nagy integer JavaScriptben pontatlanná válhat. UUID vagy stringként serializált numerikus ID biztonságosabb lehet, ha a formátum pontosan dokumentált.

Az enum válaszoldalon bővülhet

A szerver új rendelési állapotot vezethet be. Egy fallback nélküli exhaustive switch összeomolhat. A response enumot nyitottnak kell kezelni ott, ahol a termék fejlődése várható.

Requestben viszont a szerver szigorúan validál. Ismeretlen műveletet nem hajthat végre találgatás alapján. Az adat iránya meghatározza a kompatibilitási politikát.

A válaszburkolat teret ad metaadatnak

Kollekciónál a data, pagination, links és metadata elkülönítése lehetővé teszi új cursor vagy warning hozzáadását a lista típusának megváltoztatása nélkül.

A hibaburok tartalmazzon stabil gépi code-ot, emberi üzenetet, request ID-t és mezőhibákat. A kliens ne lokalizált szöveget parsoljon vezérlési döntéshez.

A dátum és a pénz különösen pontos szerződést kér

Egy instant egyértelmű ISO 8601 alakban offsettel vagy pontosan nevezett epoch egységben utazzon. A local date nem alakítható automatikusan UTC éjféllé.

Pénzösszeghez pénznem és lebegőpontos meglepetést elkerülő reprezentáció kell. Ezeket később nagyon nehéz kompatibilisen megváltoztatni.

A pagination stabil rendezést igényel

Offset pagination közben új rekordok érkezhetnek, ezért elemek ismétlődhetnek vagy kimaradhatnak. Stabil sorrendre épülő cursor nagy, gyorsan változó listán jobb.

A szerződés rögzítse a sort ordert és tie-breakert. Enélkül a cursor sem ad megismételhető folytatást.

A verziószám nem helyettesíti a kompatibilitást

Új URL-verzió indokolt lehet valóban inkompatibilis változásnál, de minden verzió megsokszorozza a dokumentációt, tesztelést és supportot. A legtöbb fejlődés kompatibilis bővítéssel olcsóbb.

Az új verzióhoz migrációs útmutató, adoption telemetry és a régi lezárási dátuma kell. Az, hogy a v2 létezik, nem bizonyítja a kliensek átállását.

Az írási művelet legyen idempotens

Timeout után a kliens nem tudja, létrejött-e a rendelés. Idempotency key segítségével ugyanaz a logikai kérés visszakaphatja az eredeti eredményt. Azonos kulcs eltérő bodyval konfliktus legyen.

A kulcsot felhasználóhoz és endpointhoz kell kötni. A JSON mezősorrendje nem döntheti el, ugyanarról a műveletről van-e szó.

A deprecated használatot mérni kell

A dokumentációban áthúzott mező nem elég. Client ID, SDK-verzió és endpoint metrika mutassa, ki küldi vagy olvassa még. Így a tulajdonos kapcsolatba léphet a partnerrel.

Az átmeneti kompatibilitási ág a migráció végén eltávolítandó, különben minden további változás több viselkedéskombinációt tart életben.

A contract test mindkét felet védi

A sémateszt ellenőrzi a típusokat, consumer-driven contract pedig megmutatja, mire támaszkodik valójában a kliens. Produkciós mérés bizonyítja, hogy egy régi változat eltávolítható.

A változásálló API nem mozdulatlan. Kiszámíthatóan fejlődik: új lehetőséget ad, ideiglenesen megőrzi a régi jelentést, és csak bizonyíték alapján zárja le. A legfontosabb tulajdonság nem a tökéletes első séma, hanem a biztonságos út két állapot között.

A producer és consumer külön ütemben települ

Egy eseményvezérelt rendszerben a queue órákig vagy napokig őrizhet régi payloadot. Az új consumernek ezért nemcsak a jelenlegi producerrel, hanem a már tárolt üzenetekkel is kompatibilisnek kell maradnia. Egy mező eltávolítása előtt a retention időt és a dead-letter queue tartalmát is figyelembe kell venni.

A blue-green vagy rolling deployment idején több verzió egyszerre fut. A szerződésnek átmenetileg mindkét irányban működnie kell: az új producer üzenetét a régi consumer, a régi producerét az új consumer is feldolgozza, vagy a rollout sorrendje ezt tudatosan kizárja.

A változás kockázata a jelentésben is megjelenik

Egy mező típusa változatlan maradhat, miközben üzleti jelentése módosul. A status: active például korábban fizető ügyfelet, később csak engedélyezett fiókot jelenthet. A séma ezt nem feltétlenül észleli.

A szemantikai változás új mezőt vagy új enumértéket érdemel. Dokumentáció, példák és contract tests mellett doménméréseknek is egyértelműen igazolniuk kell, hogy a kliensek nem a régi jelentésre építenek.