A REST API használatának alapjai
Hogyan érhetik el külső rendszerek a rendszer adatait: API-kulcs, a kérés és a válasz felépítése, hibakódok és az interaktív API-dokumentáció.
A rendszer REST API-ja külső programoknak (például egy könyvelőprogramnak vagy saját webes felületnek) ad hozzáférést a partner-, cím- és bankszámla-adatokhoz, valamint az előfizetés-rendeléshez. Minden hívás egy személyes API-kulccsal történik, és a kulcs tulajdonosának jogaival fut.
Az első hívás lépései
- Kérjen API-kulcsot a felhasználójához. A kulcs a felhasználói beállításoknál (Felhasználók → API-kulcs) kezelhető; ott vonható vissza is.
- Kérje meg a rendszergazdát, hogy a felhasználója kapja meg azokat a funkciójogokat és cégekre vonatkozó tartalmi jogokat, amelyeket az API-n is használni szeretne. Az API pontosan azt engedi, amit a felület.
- Nyissa meg az interaktív API-dokumentációt (a webcímet a rendszergazdától kapja). A dokumentáció a rendszer saját végpontjaiból automatikusan épül fel.
- Adja meg a dokumentációs oldalon az API-kulcsot, válasszon egy végpontot, például a partnerlistát, és indítsa el a próbahívást.
- Ellenőrizze a választ: siker esetén az adat, hiba esetén egy rövid üzenet és egy gépi hibakód érkezik.
Hibakódok
| Hibakód | Jelentés |
|---|---|
| 401 | hiányzó vagy érvénytelen API-kulcs |
| 403 | nincs funkciójog, vagy a cég kívül esik a tartalmi jogán |
| 404 | a keresett rekord nem létezik |
| 409 | ütközés, például a törölni kívánt címet cégek használják |
| 422 | hibás vagy hiányzó adat |
| 500 | váratlan szerverhiba |
| 503 | a rendszer éppen frissül; két perc múlva érdemes újrapróbálni |
Az API-kulcs olyan, mint egy jelszó. Ne tegye nyilvános helyre, és ha kiszivárgott, vonassa vissza.
Példa
A Minta Kft. webshopja egy új vevő adószámával lekérdezi, létezik-e már a partner. A válasz 200-as kóddal megadja a partner adatait, címeit és bankszámláit; ha a partner egy olyan cégcsoportba tartozik, amelyhez a kulcs tulajdonosának nincs joga, nem kap találatot.