API-integráció tervezése: mit tisztázz fejlesztés előtt?
Az adatgazdától a hibakezelésig: ezek a kérdések választják el a stabil rendszerkapcsolatot a törékeny adatmásolástól.
RÖVIDEN A LÉNYEG
Egy API-integráció tervezése előtt rögzíteni kell a hiteles adatforrást, az átadott mezőket, az engedélyezett műveleteket, a hozzáférés módját és a hibák kezelését. Az is legyen egyértelmű, mi történik időtúllépés, ismételt kérés vagy részleges siker esetén, ki látja az elakadást, és hogyan ellenőrizhető az átadás. Az API megléte önmagában még nem teszi megbízhatóvá a folyamatot.
- Adatkörönként jelölj ki hiteles forrást és felelőst.
- Az ismételt kérés ne hozzon létre duplikált üzleti műveletet.
- A napló mutassa meg az állapotot, de ne másoljon felesleges érzékeny adatot.
1. Döntsd el, melyik rendszer miben hiteles
Az ügyfél neve lehet a CRM-ben, a számla állapota a számlázóban, a jogosultság pedig a belső rendszerben hiteles. Ne egyetlen általános „főrendszert” keress: adatkörönként rögzítsd, honnan származik az érték, melyik rendszer módosíthatja, és mi történik ellentmondáskor. Egy kétirányú kapcsolat különösen könnyen hoz létre végtelen felülírást vagy régi adat visszatöltését, ha nincs egyértelmű adatgazda.
Írd le a kiváltó eseményt és a kívánt üzleti eredményt is. Más megoldás kell ahhoz, hogy naponta egyszer szinkronizáljatok egy listát, mint ahhoz, hogy egy jóváhagyás után azonnal létrejöjjön egy következő feladat. A gyakoriság, a késés elfogadható mértéke és az emberi beavatkozás helye már a tervezés elején legyen látható.
2. Készíts mezőtérképet és ellenőrizhető szerződést
Minden átadott mezőhöz rögzítsd a forrásmezőt, a célmezőt, a formátumot, a kötelezőséget és az átalakítás szabályát. Külön kezeld az azonosítókat, pénznemeket, időzónákat, státuszokat és a hiányzó értékeket. A „név” vagy „dátum” önmagában nem elég pontos; a félreérthető megfeleltetés gyakran csak éles adatoknál válik láthatóvá.
Az OpenAPI-leírás géppel olvasható módon dokumentálhatja a végpontokat, paramétereket és válaszokat, de nem helyettesíti az üzleti szabályokat. A tervhez ezért technikai szerződés és ember számára érthető példák is kellenek: egy hétköznapi eset, egy hiányos kérés és egy olyan válasz, amelyet a célrendszer visszautasít.
3. A hozzáférés legyen szűk és visszavonható
Ne adj át közös felhasználónevet vagy teljes jogosultságú kulcsot csak azért, mert így gyorsabb a próba. Határozd meg, melyik rendszer kezdeményez, milyen adatokhoz férhet hozzá, és mely műveleteket végezheti el. Az OAuth 2.0 korlátozott hozzáférést tesz lehetővé egy szolgáltatáshoz; a konkrét engedélyezési módot azonban mindig az adott szolgáltató dokumentációja és a működési környezet alapján kell kiválasztani.
A titkok ne kerüljenek forráskódba, űrlapadatba vagy naplóba. Legyen gazdája a kulcsok cseréjének és visszavonásának, és legyen kipróbálva az is, mi történik lejárt hozzáférésnél. A fejlesztői és éles környezet kapjon külön hitelesítést, hogy egy teszt ne módosíthasson véletlenül valódi ügyféladatot.
4. Tervezd meg az újrapróbálást duplikáció nélkül
Időtúllépéskor nem mindig lehet tudni, hogy a másik rendszer elvégezte-e a műveletet. A vak újraküldés így két rendelést, két számlát vagy két értesítést hozhat létre. Használj egyedi műveleti azonosítót, ellenőrizhető állapotot és olyan újrapróbálási szabályt, amely külön kezeli az átmeneti és a végleges hibát. Az RFC 9110 szerint az idempotens művelet ismétlése ugyanazt a szándékolt hatást eredményezi; nem idempotens kérés automatikus ismétléséhez külön védelem kell.
Vedd számba a szolgáltatói korlátokat és a torlódást is. A hibás rekord ne állítsa meg észrevétlenül az egész sort, de ne is tűnjön el. Kapjon érthető okot, felelőst és biztonságos újrafeldolgozási lehetőséget. Részleges sikernél pontosan látszódjon, melyik lépés fejeződött be és melyiket tilos megismételni.
5. Az átadás része legyen a megfigyelés és a visszaállás
A „200 OK” még nem bizonyítja, hogy üzletileg helyes adat került a megfelelő ügyhöz. Az elfogadási próba ellenőrizze a normál utat, a hiányzó mezőt, a jogosultsági hibát, az időtúllépést, az ismételt kérést és a célrendszer elutasítását. Legyen összevethető darabszám vagy egyeztetési pont, amellyel kiderül, ha valamelyik oldalon elveszett egy tétel.
Indulás után legyen látható a sikeres, várakozó és hibás műveletek száma, a legrégebbi elakadás és a beavatkozás felelőse. A napló ne tartalmazzon teljes hozzáférési tokent vagy szükségtelen személyes adatot. Dokumentáld azt is, hogyan állítható le a kapcsolat, hogyan dolgozható fel újra egy tétel, és ki értesül, ha a külső API megváltozik.
AZONNAL HASZNÁLHATÓ MINTA
API-integrációs előkészítő lap
Egyetlen adatátadáshoz rögzítsd a hiteles forrást, a mezőtérképet, a hozzáférést, az ismételhetőség szabályát, a kivételgazdát és az átadás ellenőrzését.
- Hiteles forrás és célrendszer
- Mezőtérkép és üzleti szabály
- Hozzáférés és duplikációvédelem
- Hibagazda, napló és egyeztetés
Források és további olvasnivaló
- RFC 9110: HTTP SemanticsRFC Editor · Ellenőrizve: 2026-11-02
- RFC 6749: The OAuth 2.0 Authorization FrameworkRFC Editor · Ellenőrizve: 2026-11-02
- OpenAPI Specification 3.1OpenAPI Initiative · Ellenőrizve: 2026-11-02
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.