Rendszerintegráció tervezése: mit tisztázz az API-fejlesztés előtt?
Az API csak a kapcsolat technikai része. A működő integrációhoz adatgazda, egyértelmű azonosítók, hibakezelés, jogosultság és felügyelet is kell.
RÖVIDEN A LÉNYEG
Rendszerintegráció előtt rögzítsd, melyik rendszer mely adat hiteles forrása, mi indítja az adatátadást, hogyan azonosítható ugyanaz az ügy mindkét oldalon, és mi történik hibánál vagy ismételt kérésnél. Csak ezután érdemes végpontokról és technológiáról dönteni. Az elfogadási próba a normál út mellett duplikációt, hiányos adatot, jogosultsági hibát és átmeneti leállást is fedjen le.
- Minden adatmezőnek legyen megnevezett hiteles forrása.
- Az ismételt kérés ne hozzon létre észrevétlen duplikációt.
- A hibákhoz tartozzon látható állapot, felelős és biztonságos újrafeldolgozás.
A rendszerhatár előtt az üzleti eseményt írd le
Ne azzal kezdd, hogy „kell egy API”. Válassz egy teljes eseményt, például egy jóváhagyott rendelés átadását a számlázó felé. Írd le, mi indítja, mely adatok szükségesek, melyik rendszerben születik meg a döntés, és milyen állapot bizonyítja a sikeres lezárást. Ha ezt a folyamatot nem lehet egyértelműen elmondani, a végpontlista sem fogja megoldani a felelősségi bizonytalanságot.
Különítsd el a valós idejű igényt a kényelmi elvárástól. Van, amit azonnal át kell adni, más adatnál egy ellenőrzött időszakos feldolgozás biztonságosabb és egyszerűbb lehet. A megfelelő forma attól függ, milyen késés elfogadható, hogyan lehet visszaállni, és mekkora következménye van egy kimaradt vagy kétszer feldolgozott eseménynek.
Nevezd meg az adatgazdát és az azonosítót
Minden átadott mező mellett legyen világos, melyik rendszer számít hiteles forrásnak, ki módosíthatja, és mikor kell frissíteni. Ugyanaz a név vagy e-mail-cím önmagában ritkán stabil üzleti azonosító. Használj tartós belső azonosítót, és dokumentáld a két rendszer azonosítói közötti megfeleltetést. Az összevonás, törlés és újranyitás eseteit is írd le.
Készíts mezőtérképet adattípussal, kötelezőséggel, megengedett értékekkel és érzékenységi jelöléssel. Személyes adatból csak azt add át, ami a meghatározott célhoz szükséges. Az adatminimalizálás nem utólagos takarítás: a kapcsolati szerződés és a tesztadat összeállításának része.
A kapcsolati szerződés legyen ellenőrizhető
Dokumentáld a műveletet, a bemenetet, a választ, a hibakódokat és a verziózást. Az OpenAPI leírás segíthet abban, hogy a fejlesztők és a tesztek ugyanazt a szerződést értsék, de a fájl önmagában nem helyettesíti az üzleti szabályokat. Írd le például azt is, hogy egy státusz mikor tekinthető véglegesnek, és mely mezők módosíthatók később.
A jogosultság legyen a szükséges minimumra korlátozva. Külön hozzáférés tartozzon a teszt- és éles környezethez, a titkok ne kerüljenek forráskódba vagy naplóba, a hozzáférés pedig legyen visszavonható. A változtatásokhoz legyen kompatibilitási döntés és értesítési rend; egy néma mezőátnevezés üzleti folyamatot állíthat meg.
Tervezd meg az ismétlést és a hibautat
Kapcsolati hiba után nem mindig tudható, hogy a másik rendszer végrehajtotta-e a kérést. Az automatikus újrapróbálás ezért csak akkor biztonságos, ha a művelet természeténél vagy külön műveleti azonosítónál fogva idempotens. Az IETF HTTP-szabványa is megkülönbözteti az idempotens és nem idempotens kérések ismétlését; egy sikertelennek látszó POST vak újraküldése duplikációt okozhat.
Határozd meg az időtúllépést, a visszalépési rendet, a próbálkozások számát és azt, mikor kerül egy ügy emberi ellenőrzési sorba. A hibarekord tartalmazza a művelet azonosítóját, időpontját, állapotát és a következő teendőt, de ne másolja szükségtelenül az érzékeny teljes adatcsomagot. A csendes adatvesztés helyett legyen látható, javítható állapot.
Próbáld végig és add át működtethetően
Az elfogadási teszt fedje le a normál ügyet, a hiányzó kötelező mezőt, a kétszer érkező eseményt, a lejárt hozzáférést, a szolgáltatói korlátozást és az átmeneti leállást. Ellenőrizd azt is, hogy részleges siker után hogyan áll helyre az összhang. Anonimizált vagy mesterséges tesztadatot használj, és előre rögzítsd, mitől számít sikeresnek minden eset.
Élesítéskor legyen felügyelet, riasztási küszöb, felelős és visszaállítási terv. Az átadás része a mezőtérkép, a kapcsolati leírás, a hozzáférések nyilvántartása, a hiba-újrafeldolgozási eljárás és a változtatási felelősség. A NIST SSDF szemléletével összhangban a biztonság és a javíthatóság a teljes életciklus feladata, nem egyszeri élesítés előtti ellenőrzés.
Források és további olvasnivaló
- OpenAPI Specification v3.0.4OpenAPI Initiative · Ellenőrizve: 2026-10-31
- RFC 9110: HTTP Semantics — Idempotent MethodsRFC Editor · Ellenőrizve: 2026-10-31
- Secure Software Development Framework (SSDF) Version 1.1NIST · Ellenőrizve: 2026-10-31
- General Data Protection Regulation, Article 5European Union · Ellenőrizve: 2026-10-31
Kapcsolódó kérdések
Mit kell tisztázni egy API-integráció fejlesztése előtt?
Rögzítsd az üzleti eseményt, az adat hiteles forrását, a két rendszer tartós azonosítóit, a mezőtérképet, a jogosultságokat és a sikeres lezárás állapotát. Ezután tervezd meg a végpontokat, a verziózást, a hibakódokat és az elfogadási teszteket.
Hogyan kezelhető biztonságosan egy rendszerintegráció hibája?
Minden művelet kapjon egyedi azonosítót és látható állapotot. Az újrapróbálás csak idempotens műveletnél legyen automatikus; más esetben előbb ellenőrizni kell, megtörtént-e a változás. Legyen korlátozott próbálkozásszám, emberi ellenőrzési sor, naplózott következő teendő és felelős.
Borbély Kristóf
A Kriside mögött álló fejlesztő. Gyakorlati útmutatókat ír webes rendszerekről, automatizációról és AI-megoldásokról.