Mi az API? Egyszerű útmutató app-építőknek

Az API (alkalmazásprogramozási felület) egy meghatározott módja annak, ahogy egy szoftver adatot kér egy másiktól, vagy arra kér, hogy tegyen valamit. Az appod egy megállapodott formátumú kérést küld — „add meg a holnapi foglalásokat”, „terhelj le 20 eurót erről a kártyáról”, „foglald össze ezt a szöveget” —, a másik rendszer pedig strukturált választ küld vissza. Az API-k teszik lehetővé, hogy egy app részei beszéljenek egymással, és ezen keresztül használja az app a külső szolgáltatásokat, például a fizetést, az e-mailt, a térképeket és az AI-t.

Miért fontosak az API-k, ha AI-val építesz

Szinte minden hasznos app olyan részekből áll, amelyek API-kon keresztül kommunikálnak:

• Az app belsejében a böngészőben lévő képernyők a saját backendjük API-ját hívják adatok betöltésére és mentésére.
• Az app külsején a backendod más cégek API-it hívja: a Stripe fizetést vesz fel, egy e-mail-szolgáltató visszaigazolásokat küld, egy AI-modellszolgáltató szöveget generál.

Amikor azt kéred az AI-építődtől, hogy „vegyen fel fizetést” vagy „adjon hozzá AI-összefoglalót”, valójában egy API-t hívó kódot ír. Az alapok ismerete segít megérteni, mire van szüksége tőled az AI (általában egy fiók az adott szolgáltatónál és egy API-kulcs), hol csúszhatnak el a dolgok, és mibe kerülnek.

Egy hétköznapi hasonlat

Gondolj egy étteremre. Nem mész be a konyhába főzni. Elolvasod az étlapot, megmondod a pincérnek, mit szeretnél úgy, ahogy a konyha érti, és a pincér visszahozza az ételt — vagy megmondja, hogy az adott étel elfogyott.

• Az étlap az API-dokumentáció: lista arról, mit kérhetsz és hogyan.
• A pincér az API: a kérések bejutásának és a válaszok kijutásának egyetlen, megállapodott módja.
• A konyha a másik rendszer: nem kell tudnod, hogyan működik belül.
• A rendelésed a kérés; a tányér a válasz.

A konyha átalakíthatja a sütőit és a személyzetét anélkül, hogy téged érintene, amíg az étlap ugyanaz marad. Ez az API valódi értéke: két rendszer tud együtt dolgozni anélkül, hogy egyiknek is tudnia kellene, a másik hogyan épül fel.

Hogyan működik egy webes API-kérés

A legtöbb API, amellyel találkozol, HTTP-n keresztül működő webes API, ugyanazt a protokollt használva, mint a böngésződ. Minden kérésnek van néhány része:

És minden válasznak van:

A JSON (JavaScript Object Notation) egyszerű szöveges formátum: nevek és értékek kapcsos zárójelek között. Ez a webes API-k szabványos adatcseréje.

REST: a leggyakoribb stílus

A REST egy széles körben használt konvenció webes API-k tervezésére. Minden típusú dolognak saját URL-je van, a szabványos metódusok pedig megmondják, mit teszel vele. Így nézhet ki egy REST API egy foglalási appnál:

A PUT is létezik, és hagyományosan egy teljes rekordot cserél le, míg a PATCH csak a elküldött mezőket változtatja meg.

A leggyakrabban látott státuszkódok:

Ha az appod elromlik, a státuszkód gyakran a leggyorsabb támpont. Egy 401 egy fizetési szolgáltatónál általában hiányzó vagy hibás API-kulcsot jelent; a 429 azt, hogy túl gyakran hívod.

A REST nem az egyetlen stílus — léteznek GraphQL- és RPC-jellegű API-k is —, de a REST az, amit a legtöbb szolgáltatás és AI-val épített backend használ.

Kidolgozott példa: egy foglalás visszaigazolása

Amikor egy vásárló hajvágást foglal egy szalonappban, néhány másodperc alatt több API-hívás történhet:

1. A böngészőben lévő foglalási oldal POST /api/bookings kérést küld a szolgáltatással, az időponttal és a vásárló adataival a backendednek.
2. A backend ellenőrzi, hogy a szabad az időpont, elmenti a foglalást az adatbázisba, és 201 Created választ ad.
3. A backend meghívja az e-mail-szolgáltató API-ját a titkos kulcsával: „küldd ezt a visszaigazolást a lena@example.com címre”.
4. Ha van előleg, a backend megkéri a fizetési szolgáltató API-ját, hogy hozzon létre fizetési munkamenetet, és odairányítja a vásárlót.
5. Később a fizetési szolgáltató hozzád hív, hogy közölje: a fizetés sikeres volt. Ez a fordított hívás egy webhook.

Az első két lépés a saját API-d a frontend és backend között. A 3–5. lépés külső API-k.

Gyakori kifejezések magyarázata

Gyakori hibák és tévhitek

• Titkos kulcsok a frontenden. Bármi, ami a böngészőben futó kódban van, bárki számára látható, aki meglátogatja az oldalt. A titkos kulcsoknak a szerveren kell maradniuk, környezeti változókban vagy titkokban.
• Kulcsok beillesztése a csevegésbe. A csevegési előzmények tárolódhatnak. Használd helyette az építő titokkezelő funkcióját, és cseréld le a kulcsot, ha kiszivárgott.
• Azt hinni, hogy az API ingyenes. Sok API kérésenként vagy használat alapján számláz — az AI-modellek API-i tokenenként. Nézd meg az árakat, és állíts be költségkeretet. Lásd: hogyan használj LLM API-kat.
• A hibák kezelésének elmulasztása. A külső szolgáltatások leállnak, időtúllépést kapnak és elérik a korlátokat. Kérj értelmes hibaüzeneteket és újrapróbálkozást.
• A böngészőnek való vakbizalom. A saját API-dnak magának kell ellenőriznie a jogosultságokat. Egy gomb elrejtése nem akadályozza meg, hogy valaki közvetlenül hívja a végpontot.
• Éles kulcsok használata teszteléskor. Használj teszt-mód kulcsokat, amíg nem állsz készen az indulásra.

Mit kérj az AI-építődtől

• „Mely külső API-kat használja ez az app, és mindegyik mennyibe kerül?”
• „A fizetési API-t csak a szerverről hívd. A kulcsot környezeti változóból olvasd.”
• „Sorold fel az API minden végpontját, mit csinál, és kik hívhatják.”
• „A szerveren ellenőrizd, hogy a bejelentkezett felhasználó tulajdonosa-e a foglalásnak, mielőtt módosítod vagy törlöd.”
• „Ha az e-mail API meghibásodik, mentsd el a foglalást mindenképp, és naplózd a hibát.”
• „Egyelőre a szolgáltató teszt-módját használd.”

API-k a Mythexben

A Mythex építhet saját API-t — egy webapp részeként, vagy külön backendként Node, Python (FastAPI), C# vagy Java nyelven, a frontenddel együtt futva —, és megírhatja a külső szolgáltatásokat hívó kódot. Az API-kulcsaidat projekttitokként add meg, nem a csevegésben, és ezek az appodban elérhetők lesznek az előnézetben és publikálás után is. A dokumentációban van recept az bármilyen API integrálásához és a REST API backend építéséhez.

Kérdések