Határozza meg, mi számít nyilvános szerződésnek, az új, nem kötelező lehetőségeket kompatibilis módon vezesse be, a meglévő mezők jelentését ne változtassa meg csendben, nem kompatibilis változás esetén pedig hozzon létre egyértelmű verziót migrációs útmutatóval, támogatási határidővel, szerződéses tesztekkel és az aktív kliensek monitorozásával.
Az API-verziózás azt a helyzetet kezeli, amikor a szolgáltató és a kliensek igényei eltérő ütemben fejlődnek. Egy mezőnév, egy állapot jelentése vagy egy kötelező jelleg megváltoztatása akkor is károsíthatja az integrációt, ha az endpoint továbbra is válaszol. Világos szabályzat nélkül a csapat vagy fél javítani a szerződést, vagy éppen ellenkezőleg, rendszeresen inkompatibilis módosításokkal lepi meg a klienseket.
A legjobb új verzió gyakran az, amelyet nem kell létrehozni, mert a változtatás kompatibilis módon hozzáadható. Ha az inkompatibilitásnak van értelme, átmeneti időszakra, dokumentációra, tesztkörnyezetre és az aktív fogyasztók ismeretére van szükség. A verzió nem csupán egy szám az URL-ben; magában foglalja a sémát, a viselkedést, a hibákat és az üzemeltetési elvárásokat.
Határozza meg az interfészszerződést és a kompatibilitást
A szerződés magában foglalja az útvonalakat, metódusokat, mezőket, típusokat, kötelező jelleget, enumokat, állapotkódokat, a műveletek sorrendjét és jelentését. A gyakorlatban ide tartozik a korlát, a lapozás, a hitelesítés és az időbeli viselkedés is. A belső kód módosítása addig nem API-változás, amíg nem változtatja meg a kliens megfigyelhető elvárásait. Ezt a kört rögzítse és tartsa karban egyetlen hiteles helyen.
A visszafelé kompatibilitás azt jelenti, hogy egy meglévő, helyesen megírt kliens kényszerű módosítás nélkül tovább működik. Egy nem kötelező mező hozzáadása általában csak akkor kompatibilis, ha a kliens a szerződésnek megfelelően tolerálja az ismeretlen értékeket. Egy új enumérték hozzáadása tönkreteheti a zárt elágazást (switch-et). A valós viselkedést értékelje, ne csupán a szintaktikai sémát.
Részesítse előnyben a kompatibilis továbbfejlesztést
Az új mezőt először opcionálisként adja hozzá, töltse fel adatokkal, és tegye lehetővé a kliensek számára az átállást. A régi mezőt tartsa meg a megállapodott időszak alatt, és kövesse nyomon a használatát. Ne változtassa meg a mértékegységet, az időzónát vagy a jelentést új név vagy verzió nélkül. A szervernek ésszerűen tolerálnia kell a kérés lényegtelen bővítését, ha ezt a biztonság megengedi.
A viselkedés megváltoztatásakor rejtett átkapcsolás helyett fontolja meg egy új, explicit képesség vagy paraméter bevezetését. Az alapértelmezett értéknek meg kell őriznie a meglévő kliensek elvárásait. Az ideiglenes kettős implementáció növeli a karbantartási terhet, ezért felelőst és eltávolítási dátumot igényel. A kompatibilitás nem ok arra, hogy terv nélkül mindent örökké fenntartsunk.
- opcionális hozzáadás az eltávolítás előtt
- új név a jelentés megváltozásakor
- biztonságos alapértelmezett érték
- nyomon követett átállás befejezési dátummal
Vezesse be a verziót a megfelelő határon
A verzió kifejezhető az URL-ben, egy fejlécben, az eseménysémában vagy más támogatott mechanizmussal. Válasszon egyetlen következetes megközelítést a platform és a terjesztés módja szerint. Ne vezessen be új főverziót minden apróságért. Egy olyan inkompatibilis elvárás-csomagot kell képviselnie, amelyet a kliens tudatosan választhat és tesztelhet.
A webhooknak és a kötegelt exportnak saját payloadverzióra van szüksége, még ha ugyanazokat a domainfogalmakat használják is, mint a REST API. A verziót az eseménnyel együtt tárolja, hogy a fogadó fél később is fel tudja dolgozni. A dokumentáció ismerteti a különbségeket, a migrációs példákat és az ismert korlátokat. A régi és az új példák jelölés nélkül nem keveredhetnek.
Jelezze előre az elavulást és támogassa a migrációt
A kivezetés előtt mérje fel az aktív klienseket és a tulajdonosaik elérhetőségeit. A bejelentésnek tartalmaznia kell az okot, a helyettesítő megoldást, az eltéréseket, a tesztelési lehetőségeket, a határidőket és a támogatási csatornát. Kritikus partner esetén nem elegendő egyetlen megjegyzés a változásnaplóban. Az átmeneti időszakot a kockázat és a szerződések alapján határozza meg, ne egyetlen csapat kényelme szerint.
Biztosítson migrációs útmutatót és tesztforgatókönyveket. Ha a régi használat automatikusan észlelhető, jelenítsen meg figyelmeztetést a portálon vagy a válaszban információszivárgás nélkül. A kikapcsolás előtt ellenőrizze az aktivitás csökkenését, és eszkalálja az ismeretlen fogyasztókat. A határidő után ellenőrzötten távolítsa el a régi kódot, és figyelje a váratlan hibákat.
Automatizálja a kontraktusteszteket és a megfigyelést
A sémát validálja CI-ben, és vesse össze a legutóbb kiadott verzióval. A szolgáltatói tesztek ellenőrzik a példákat és a szabályokat, a fogyasztói szerződések pedig a valós kliensek fontos elvárásait rögzítik. Ne tekintse ezeket az integráció teljes értékű helyettesítőjének; az adatok jelentése és a működési korlátok end-to-end forgatókönyveket igényelnek biztonságos környezetben.
Éles környezetben kövesse a verziót, a klienst, a validációs hibákat és az elavult mezők használatát túlzott profilozás nélkül. A változtatást fokozatosan vezesse be, és készítse elő a visszaállítást. Minden incidens frissíti a szabályzatot és a teszteket. A jól irányított verziózás lehetővé teszi, hogy az API fejlődjön anélkül, hogy minden fejlesztés összehangolt leállássá válna.
- a kiadások nyilvános sémájának automatikus összehasonlítása
- a kritikus integrációs partnerek fogyasztói elvárásai
- korábbi mintakérések kompatibilitási tesztje
- a régi verziót használó kliensek monitorozása
- a migrációs útmutató ellenőrzése tesztkörnyezetben
- a régi verzió kivezetési határidejének egyértelmű felelőse
- a nem használt kompatibilitási kód ellenőrzött eltávolítása
Gyakori kérdések
Szerepelnie kell az API verziójának az URL-ben?
Nem. Lehet az URL-ben, a fejlécben vagy más egyeztetett mechanizmusban. A lényeg a következetesség, a kliens egyértelmű választása, a dokumentáció és az átállás üzemeltetésének képessége.
Mindig kompatibilis egy új mező hozzáadása?
Nem mindig. A kliens elutasíthatja az ismeretlen mezőket vagy az új enum értékeket. A szerződésnek meg kell határoznia a toleranciát, a változtatást pedig tesztekkel és az aktív fogyasztók viselkedésével kell ellenőrizni.
Meddig támogassuk a régi verziót?
A szerződések, az ügyfelek száma, a kockázat és a migráció nehézsége alapján. Határozzon meg konkrét tervet, kommunikálja előre, és ellenőrizze a használatot. A határozatlan ideig tartó támogatás fékezi a biztonságos karbantartást.
Források és további olvasnivaló
Adam Antoni vyvíja weby, aplikácie a softvér na mieru. Prepája firemné systémy, automatizuje procesy a vytvára AI agentov. Pôsobí v Spišskej Novej Vsi a spolupracuje s firmami na celom Slovensku.
