RAPId bevezető
A cikk eleje fogalom-definíció helyett példákat sorol az API-ra.
A cikk második felében gyakorlatban is megnézzük web esetén az API-t bármi is legyen. Ehhez a legtöbb böngészőben alapesetben meglévő DevTools-t fogjuk használni.
AlAP Infó
Hosszas definíció-magyarázat helyet néhány, mindenki által ismert API példát írok le. Talán nem is gondolnád, de ezek is API-k:
1. példa: A Windows operációs rendszer ablakai
Ha Microsoft Windows operációs rendszerbe illeszkedő alkalmazást szeretne valaki készíteni, akkor nem kell foglalkoznia azzal, hogy hogyan kell kirajzolni egy ablakot, hogyan kell rátenni a “Tálcára”, “Teljes méret” és a “Kilépés” gombokat. Ezekhez csak meg kell hívnia a Windows megfelelő eljárásait, amik ezeket a feladatokat elvégzik.
A Windows ablakainak a kezeléséhez az eljárásokat API-n keresztül teszi elérhetővé.
2. példa: Játékok kommunikációja a videókártyákkal
A videókártyák biztosítanak olyan eljárásokat, amik lehetővé teszik a szoftverek számára, hogy közvetlenül kommunikáljanak a videókártyával. Ezek az eljárások segítségével a fejlesztők kihasználhatják a videókártya hardveres képességeit, mint például a 3D grafikus számításokat, textúrázást és raszterizálást. Ezek jelentősége játékok és más grafikailag intenzív alkalmazások fejlesztésénél is nagy, mivel a gyors és hatékony grafikus teljesítmény kulcsfontosságú.
A videókártyákhoz biztosított eljárások API-kon keresztül hozzáférhetők.
3. példa: Bankok és a PSD2
A PSD2 közös EU-s irányelv, ami számos lehetőséget biztosított. Pl:
- Pénzügyi aggregátorok: Ezek az alkalmazások lehetővé teszik a felhasználók számára, hogy egyetlen platformon keresztül kezeljék különböző banki számláikat és pénzügyeiket.
- Fizetési kezdeményezési szolgáltatók (PISP): Harmadik fél közvetlenül kezdeményezhet fizetéseket az ügyfelek banki számláiról, ami alternatívát nyújthat a hagyományos banki átutalásokhoz és kártyás fizetésekhez.
- Számlainformációs szolgáltatók (AISP): Ezek a szolgáltatók összegyűjtik és elemzik az ügyfelek pénzügyi tranzakcióit, segítve őket a költségvetés tervezésében és a pénzügyi döntések meghozatalában.
- Fintech startupok: A PSD2 nyílt bankolási környezete lehetőséget ad a fintech vállalkozásoknak, hogy innovatív pénzügyi termékeket és szolgáltatásokat fejlesszenek ki, mint például személyre szabott hitelajánlatok vagy automatizált megtakarítási megoldások.
A PSD2 irányelv betartásához a bankok API-kat hoztak létre, amiken keresztül (megfelelő jogosultságokkal) elérhetők az említett lehetőségek.
4. példa: Webalkalmazások
A webalkalmazások olyan alkalmazások, amiket egyszerre többen, több helyről használnak (kliensek), de az alkalmazás üzleti része egy helyen (a szerveren) található. A szerver és a kliens közötti kommunikáció API-n keresztül történik.
Mi a közös az előző példákban?
Az API.
Minden esetben arról van szó, hogy előre megírt eljárásokat használhatunk, nem nekünk kell ezeket megírni. Ezekhez az eljárásokhoz biztosítanak számunkra valamilyen elérési lehetőséget.
- A Windows esetében a gépen találhatók az eljárások különböző állományokban.
- A videókártyák esetén szintén a gépre kell letölteni a megfelelő állományokat, amikben a meghívható eljárások vannak
- PSD2 esetén a bank biztosít interneten elérhető végpontokat (lényegében URL-ek). A végpontokhoz a szerveren lévő eljárásokat kötik. A kliensek ezeket a végpontokat tudják megfelelően paraméterezve meghívni
- Webalkalmazásnál sokféleképpen megoldható az API. Úgy is, ahogy a PSD2 esetén és úgy is, hogy a különböző megjelenő form-okhoz szerver oldalon különböző eljárásokat társítanak. Ez utóbbi lényegében a Web API.
MindennAPI
A Web API működésébe hétköznapi halandóként is be tudunk tekinteni. A legtöbb böngészőben van erre egy beépített tool: DevTools. A legtöbb böngészőben a főmenüből vagy az F12-vel lehet betölteni. Ebben a cikkben a Chrome böngészőben található DevTools-t használjuk, de a többi is nagyon hasonló.
Előkészületek
A cikk kedvéért feltelepítettem magamnak egy Redmine-t. A Redmine egy open source, ingyenesen használható projekt-menedzsment és issue kezelő eszköz. Azért ezt választottam, mert létezik hozzá egy RestAPI könyvtár ami segítségével a Postman lehetőségeit be tudom mutatni.
A “feltelepítés” soklépéses műveletsorát igyekszem ilyenkor megspórolni, ezért a Bitnami által összeállított virtuális gépet tettem egy VirtualBox-ba. Innen szereztem be: https://bitnami.com/stack/redmine/virtual-machine
A virtuális gép elindulása után megadja a szerver címét és a Redmine belépéshez az admin adatokat, amit első indításkor generál le a rendszer.
DevTools: submit
Nézzük meg a Redmine-unkban, hogy ha a bejelentkezés formon lévő információt átküldjük a szerverhez, akkor milyen információs csomag megy át. Ehhez tudnunk kell, hogy a formhoz tartozó információk akkor “kezdenek közlekedni”, amikor a formhoz tartozó submit típusú gombot megnyomjuk. A mi esetünkben ez a gomb a Belépés gomb.
Hogy honnan tudom, hogy a Belépés gomb a submit gomb? Már ennek a kinyomozásához is használhatjuk a DevTools eszközt. A Redmine belépés oldalán nyomjuk meg bátran az F12 gombot. Ne ijedj meg, ami megnyílt az a DevTools.
Van egy “nyomozó” eszköz a DevTools bal felső sarkában:
Ennek a segítségével, ha ráklikkelsz a Bejelentkezés gombra, akkor a DevTools megjeleníti a megjelenített oldal (kiszámolt) html kódját. Ebben látszik, hogy a gomb típusa “submit” és az is, hogy a login form-hoz tartozik.
Mielőtt továbblépnénk, válasszuk ki a Network fület a DevTools-ban. Itt lehet nyomonkövetni a kimenő kéréseket és a beérkező válaszokat. Sokfajta csomagot lehet figyelni, nekünk csak a Webkérés és válaszra lesz szükségünk, ezért a Network fül alatt a Doc szűrőt kell kiválasztani. (Ha Firefox bngészőben csinbnálod, akkor a HTML lesz ennek megfelelő).
Az admin felhasználóval lépünk be, alapesetben a neve: user. A belépési jelszavát a példa kedvéért cseréltem le, ilyen jelszót senki, sehol ne használjon! Az Azonosító és a Jelszó megadása után a Bejelentkezés gombra belépteti a felhasználót, közben a DevToolsban már látható is mi történt:
Megjegyzés: A képen látható Waterfall oszlopban látszik a kérések sorrendjének és időbeli lefutásának a diagramja. Ez kezdőknek hasznos lehet, de az újabb DevTools-ban ez alapértelmezetten ki van kapcsolva. Ha be akarod kapcsolni, akkor a táblázatt címsorában, bármely mezőre klikkelj a jobb-egérgombbal, keresd meg a Waterfall értéket és jelöld ki.
Két kérés ment ki. Először egy login kérés, majd egy másik kérés a szerver url-jére.
Request (kérés)
Egy web kérésnek több összetevője is van. A legfontosabbak:
- Metódus: alapvetően ezek közül az egyik: GET, POST, PUT, DELETE. Később látni fogjuk, melyik milyen esetben használatos.
- Header: Több, a kérésre vonatkozó paraméter található itt. Web kérés esetén ezeket a böngésző automatikusan kitölti. Jelenleg számunkra a legfontosabb az URL címe.
- Törzs: Itt találhatók azok az információk, amiket el akarunk juttatni a szerverhez. Pl.: Form adatok, paraméterek, állományok…
Megjegyzés haladóknak:
Egy HTTP csomag HEADER-ből és PLAYLOAD -ból áll. A header tartalmazza azokat az információkat, amik segítenek értelmezni a “másik oldalnak” a playload tartalmát. A playload a (hasznos teher vagy felhasználói adat) tartalmazhatja pl. a törzset (body), de nem kötelező. A cikk pongyola módon keveri a playload és törzs fogalmakat, de ez a megértést nem befolyásolja. A törzs a valóságban a playload része (lehet).
Login kérés
Mindhárom összetevőt meg tudjuk vizsgálni a DevTools segítségével. Válasszuk ki a login kérés sorát. Jobb oldalt megjelenik több fül.
- Header: Az első fülön látható. Van Generál része, amiben számunkra most a metódus (Request Method) és az URL (Request URL) lesz fontos, a kérés és a válasz fejlécinformációi is megtekinthetők itt.
- Metódus: A Header részben a General alatt található. Jelen esetben POST. Amikor egy form mezőinek értékeit küldjük a szerver felé, akkor a POST metódus gyakori. Később látunk majd másra is példát.
- Törzs: A kérés törzsében utaznak a form adatai. A Playload fülön látható a tartalma. Minden fontos, de ami látványos most számunkra, az az, hogy látjuk a username és a password mezők értékeit. (Ez akkor is így van, ha https lenne a protokol. A secure rész csak ezután jönne. HTTPS esetén a jelszó elkódolva közlekedne a hálózaton, de itt még akkor is látszana.)
A válasz
Egy webes kérésre a válasz is több részből áll.
Az első fontos érték a Status Code: A státuszt a Headers fülön a General részben nézheted meg. Ez egy olyan kód, ami alapvető tájékoztatást nyújt a kérés feldolgozásának a sikerességéről. A kód értékek szabványosak, (bár ettől eltérhetnének a fejlesztők, de nem szoktak). Itt találsz egy listát a leggyakrabban használt kódokról: https://en.wikipedia.org/wiki/List_of_HTTP_status_codes (van magyar oldal is, de ez bővebb információt ad). Esetünkben 302-es kódot kaptunk, aminek érdekes a jelentése: a válasz arra kéri a böngészőt, hogy hajtson végre egy átirányítást.
Az átirányítás
A 302-es kód jelen esetben nem a legszabályosabb megvalósítás, (301-es kód szabványosabb lenne), de a lényeg a működés: arra kéri a böngészőt, hogy küldjön egy GET kérést a Location-ban megadott URL-re. A Location értéke a Response headers részben található (még mindig a Headers fülön vagyunk!)
A GET kérés-válasz
A Devtollsban a login kérés alatt látunk egy másik kérést, ennek az URL-je az, amit az előbb a Location-ban találtunk. Ezt az a kérés, amit a böngésző az előző 302-es válaszkód hatására magától küldött.
Erre a kérésre válaszul a szerver elküldi a bejelentkezés után látható oldalt.
Tester sapiens
A következő részben a fenti belépést megpróbáljuk megvalósítani Postman segítségével. Spoiler alert: a Postman megoldja ezt, de tesztelőként ezzel nem leszünk előrébb. Viszont az a tudás, amit itt felszedünk mégis hasznos lehet majd a későbbiekben. Amit a következő részben megmutatok, az valami titkos és rejtett dolog lesz, amiből jobban megértheted a webalkalmazások működését. Addig is
Jó tesztelést!
Hajrá!
