Egy API-integráció nem egyszerűen két végpont összekötése. Tisztázni kell az adatgazdát, a hitelesítést, a mezők jelentését, a hibakezelést és azt is, mi történik részleges leállás vagy ismételt kérés esetén.
Ez az útmutató a tervezési döntéseket rendezi sorrendbe: folyamatábra, adatleképezés, jogosultságok, idempotencia, újrapróbálás, naplózás és ellenőrzött bevezetés.
1. Rajzold fel az adat útját
Jelöld, melyik rendszer az adott adat elsődleges forrása, mi indítja az átadást, és hol jelenik meg az eredmény. A folyamatábrán a hibás, késő vagy hiányzó válasz útja is szerepeljen.
Kép megnyitása teljes méretben 2. Készíts mező- és állapottérképet
| Kérdés | Példa |
|---|---|
| Mi az egyedi azonosító? | Külső rendelési azonosító, nem a megjelenített sorszám. |
| Mely mező kötelező? | Devizanem, összeg és ügyfélazonosító együtt szükséges. |
| Melyik rendszer írhatja? | A számlázási státuszt csak a számlázó rendszer módosítja. |
| Hogyan törlünk? | Logikai törlés, visszavonás vagy végleges eltávolítás. |
| Mi történik ismeretlen értéknél? | Elutasítás, alapérték vagy kézi feldolgozási sor. |
3. Korlátozd a hozzáférést
- Külön integrációs fiókot vagy kulcsot használj, ne egy munkatárs személyes hozzáférését.
- Csak a szükséges műveleteket és adatkört engedélyezd.
- A titkot biztonságos konfigurációban tárold, ne forráskódban vagy naplóban.
- Legyen dokumentált kulcscsere és gyors visszavonási lehetőség.
- A bejövő webhook aláírását és időbélyegét ellenőrizd, ha a szolgáltató támogatja.
4. Készülj fel ismétlésre és részleges hibára
- Azonosítsd azokat a műveleteket, amelyek ismételt kérésnél duplikációt okozhatnak.
- Használj idempotenciakulcsot vagy külső azonosítót, ahol a fogadó API ezt támogatja.
- Csak átmeneti hibánál próbálkozz újra, növekvő várakozással és felső korláttal.
- A tartósan hibás tételek kerüljenek vizsgálható hibasorba, ne vesszenek el csendben.
- A napló tartalmazzon korrelációs azonosítót, státuszt és időpontot, de ne tartalmazzon hitelesítési titkot.
5. Vezesd be visszafordíthatóan
- Tesztkörnyezet és dokumentált próbaforgatókönyvek.
- Korlátozott adatkörrel vagy felhasználói csoporttal induló próba.
- Összevetés a forrás- és célrendszer rekordszámai között.
- Riasztás hibaarányra, várakozó sorra és szokatlan forgalomra.
- Leállítási kapcsoló és kézi feldolgozási eljárás kiesés esetére.
