Kezdőlap - Webszerkesztés - PHP - REST API és JSON

REST API

és JSON

Jegyzet

A szoftverfejlesztő szakma vizsgakövetelményei mind frontend, mind backend oldalon megkövetelik a REST API ismeretét. Úgy is fogalmazhatunk, nemcsak dolgozni kell tudni egy-egy REST API kimenetéből, hanem készíteni is tudni kell ilyesmit. De mi is a REST API? Első lépésként nézzünk meg erről egy igen jól használható videót. Mint ahogyan a videóban is elhangzik, a REST API-tól visszakapott adatformátum leggyakrabban JSON lesz. Ennek megfelelően tekintsük meg JSON-t bemutató videót is! A videók tartalmát egyetlen ábrában összefoglalva az alábbiak szerint tudjuk:

Ezek szerint a REST API használata a kliens oldali végpont felől egy URL-hívással indul. A REST API ezt követően (akár adatbázishoz is fordulva) összeállítja a válaszként küldendő adatokat, és ezeket tipikusan JSON (esetleg XML, vagy egyéb) formátumban adja vissza a kliensnek.

Nem világos? Fordítsuk le akkor konyhanyelvre:

Ahogyan a vendég az étteremben sem mehet be a konyhára, úgy egy kliens sem kaphat mindig hozzáférést egy teljes adatbázishoz. A vendégtér és a konyha között a pincér testesíti meg a kapcsolatot. Pontosan ugyanúgy, mint ahogyan teszi ezt a frontend alkalmazás és a backend program adatai között az API. Innen adódik a rövidítés is: Application Programming Interface, mely magyarul picit talán esetlenül alkalmazásprogramozási felületként emlegethető. Érdemes inkább maradni az API elnevezésnél.

Nézzünk minderre néhány gyakorlati példát! 1. Random kutyaképek

Az első példa egy meglehetősen egyszerű API. Alapvetően egy URL-t ad eredményül, ami egy véletlenszerűen választott kutyának a képét rejti. Az API elérése ezen a linken lehetséges:

		https://dog.ceo/api/breeds/image/random
	

és most éppen ezt az eredményt adta vissza:

{"message":"https:\/\/images.dog.ceo\/breeds\/kelpie\/n02105412_6770.jpg","status":"success"}

Ez egy JSON formátumú adat, amit a json_decode() függvénnyel dekódolva az alábbi tartalomhoz jutunk:

stdClass Object
(
    [message] => https://images.dog.ceo/breeds/kelpie/n02105412_6770.jpg
    [status] => success
)

Ha a dekódolás eredményt pl. egy $adat nevű változóba mentjük, abból már használhatjuk a

		$adat->message
	

kifejezést, hiszen ezzel érhetjük el a kép hivatkozását.
Ezt a kifejezést felhasználva, vagyis egy <img src='...'> tagbe helyezve már képként is megjeleníthetjük weblapunkon az eredményt - vagy éppen az alábbiak tanúsága szerint akár többet is:

A fentiek összefoglalásaként az alábbi kis képre kattintva megtekintheti a megvalósításhoz szükséges teljes forráskódot.

Hogy ennek mi értelme? Első ránézésre talán nem túl sok. Azonban ha picit jobban belegondolunk, egy készülő weboldalnak például a képmegjelenítő részét mindenképpen jó lehet vele tesztelni, hiszen folyamatosan nagyon különböző méretű és képarányú képet lehet vele megjeleníttetni saját tesztkép-gyűjtemény nélkül. De ami számunkra most ennél jóval fontosabb: általánosságban is érzékelhetjük a REST API gyakorlati lényegét felhasználói szemmel:

A REST API egy böngészőből hívandó URL-cím, mely eredményként egy rövid adatsort szolgáltat, jellemzően JSON formában.

Az API egyébként akár azt is lehetővé teszi, hogy kutyafajtánként kérjünk képeket. Erről, és az összes egyéb lehetőségről a dokumentációban olvashatunk. 2. Random user Következőként nézzük meg a randomuser.me API-ját:

		https://randomuser.me/api/
	

Az API egy lehetséges eredménye a fenti linkre kattintva tekinthető meg. Ez ismét egy JSON formátumú adathalmaz. Ha ezt a kapott eredményt a json_decode() függvénnyel dekódoljuk, akkor valóban egy random user sok-sok véletlenszerűen összeválogatott adathalmazához jutunk. Ez tesztelhető az alábbi nyomógombbal.

A kapott eredmény alapján ismét tehetünk egy fontos megállapítást:

A REST API sajátossága, hogy csak nyers adatokat szolgáltat. Az adatok hasznosításának módja kizárólag az API eredményét felhasználó weboldalon múlik.

A véletlenszerű user-adatokat gyakorlatilag bármilyen módon megjeleníthetjük. Mi most éppen egy névjegyet készítettünk belőlük, melynek az képe itt látható:

A névjegyen szereplő adatok közül tekintsünk pár példát annak bemutatására, hogyan is érhetőek el a $adat nevű változóból:

$adat->results[0]->email
$adat->results[0]->location->country
$adat->results[0]->location->street->name
$adat->results[0]->picture->medium

Bármely adat eléréséhez a generált user-adatok szerkezetét bemutató képernyő tartalma alapján szükséges dolgozni.

Fentieken túl akár táblázatban, vagy éppen adatbázisban is gondolkodhattunk volna, hiszen az API dokumentációja szerint egyszerre, vagyis egyetlen lekérdezéssel legfeljebb 5000 adatot is lekérdezhetünk. Bármelyik megközelítést is választjuk, a lényeg, hogy ez az API is a különféle teszteléseinket könnyítheti meg, ha éppen nem szeretnénk mi magunk sok-sok értéktelen tesztadat létrehozásával értékes időt pocsékolni. 3. Kriptovaluta árfolyamok

A folytatásban dolgozzunk a coingecko.com oldal árfolyam-adataival, pontosabban az oldal által kínált API-val, annak dokumentációja alapján. E leírás szerint pl. egyszerűen megtudhatjuk 1 bitcoin (BTC) aktuális értékét egyéb különböző valutákban:

		https://api.coingecko.com/api/v3/exchange_rates
	

Tegyük olvashatóvá a kapott JSON adatokat!

Így már sokkal jobban kibogozható a visszakapott eredményből a bitcoin árfolyama. Feltéve, hogy az adathalmazt ismét egy $adat változóba mentjük, úgy a bitcoin árfolyamát forintban az alábbi kifejezés tartalmazza:

		$adat->rates->huf->value
	

tehát

		1 BTC  =  23686884.333 HUF
	

Ismerjünk fel ismét egy fontos tényt:

A REST API lehetőségeit az őt bemutató dokumentáció alapján tudjuk megismerni és kihasználni. Egy API dokumentáció nélkül nem igazán használható.

4. GPS koordináták

A fenti három példával ellentétben a legtöbb API általában bemenő paramétereket is vár - funkciótól függően egyet, vagy többet -, és ezek alapján ad eredményt, vagy eredményeket. Ilyen például a Nominatim API-ja, mely egy nevével adott földrajzi hely GPS koordinátáit adja válaszul.

Tekintsünk erre egy konkrét példát: kérdezzük meg pl. Aggtelek koordinátáit:

		https://nominatim.openstreetmap.org/search?q=Aggtelek&format=json
	

A kapott eredmény könnyebb áttekinthetősége érdekében tegyük olvashatóvá a JSON adatokat:

A fenti gombbal elérhető tartalom kapcsán több dolgot is érdemes észrevennünk:

1.
Az API eredményének kiolvasását nem ez eddig látott fopen() függvénnyel értük el, hanem curl kezdetű utasítsok sokaságát látjuk a kódban. Leegyszerűsítve fogamazva a cURL egy utasításgyűjtemény, mely lehetővé teszi a kommunikációt különböző típusú szerverekkel, különféle protokolokkal. Mivel a Nominatim API-ja nem hajlandó az fopen() hatására megnyílni - aki nem hiszi, próbálja ki -, ezért szükségszerű az esetében a cURL programkönyvtár használata.

2.
Tanulmányozva az eredményként kapott JSON kódot azt láthatjuk, hogy az általunk keresett információ, vagyis Aggtelek GPS koordinátái a kapott tömb nulladik elemének [lat] és a [lon] adatmezőiben érhetőek el, melyek tehát a következőek:

48.4675104, 20.5054283

amiket a fentiek alapján az

$adat[0]->lat illetve $adat[0]->lon

kifejezésekkel értünk el.

Ennek az API fontos tanulsága:

A REST API-k jellemzően paraméterezhetőek. Eredményük a bemenetként adott paraméterek értékétől függ.

Az API-k paraméterezése többnyire a php oldalak paraméterezéséhez hasonlóan, a címben kérdőjelet követően valósul meg. 5. Vonat menetrend

Ötödikként nézzünk meg egy, a gyakorlatban is nagyon jól használható API-t: tájékozódjunk vasúti menetrendekről! Ebben a

		https://apiv2.oroszi.net/elvira
	

végpont lesz segítségünkre, mely - a fenti linkre kattintás után látható módon - mindenképpen vár legalább két paramétert: azt kell megmondanunk, honnan hová szeretnénk eljutni.
Ha pl. arra vagyunk kíváncsiak, mikor megy ma vonat Hatvanból Salgótarjánba, akkor az alábbiak szerint kell használnunk az API-t:

		https://apiv2.oroszi.net/elvira?from=Hatvan&to=Salgótarján
	

Nézzük meg az eredményt a JSON-formátum kikódolása után:

Az eredmény értelmezését az API dokumentációja, illetve azon belül is a végpont válaszainak ismertetése segíti. Eszerint a [timetable] tömb elemei rejtik a közlekedő vonatokat, benne a [starttime] az indulási időt, a [destinationtime] pedig az érkezési időt. Ezek alapján például a mai első vonat az alábbi időpontban indult, illetve érkezett:

		$adat->timetable[0]->starttime       = 04:13

		$adat->timetable[0]->destinationtime = 05:37

De ez csak az első vonat volt ma. A további vonatok adatai a tömb további elemeiben keresendőek.

A REST API eredménye több visszadott adatblokk esetén tömböt is tartalmazhat. Ebben az esetben a feldolgozás ciklus használatát igényelheti.

Jelenítsük meg az összes mai járatot táblázatban, esztétikus elrendezésben. A már célba ért vonatokat szürkével, az esetlegesen éppen most közlekedőt pirossal, a még elérhető vonatokat pedig zöld színnel jelöljük!

00:00:00

Indulás Hatvan	Érkezés Salgótarján	Hatvan - Lőrinci - Pásztó - Nagybátony - Salgótarján
04:13	05:37
06:16	07:37
08:16	09:37
10:16	11:37
12:16	13:37
14:16	15:37
16:16	17:37
18:16	19:37
20:16	21:37
22:16	23:37

Vonatindulás, illetve egy vonat célba érkezése előtt 30 másodperccel a MÁV klasszikus szignálja is hallható a weboldalon, ha ezt a funkció Ön engedélyezi. A hangok lejátszását ezen a linken ki is kapcsolhatja.

6. Időjárás előrejelzés

Az API-k egyik legnagyobb klasszikusai az időjárás előrejelzést adó interfészek. Ennek roppant egyszerű oka van: az időjárás gyakorlatilag mindenkit, és folyamatosan érdekel - vagyis lehet rá üzletet építeni. Az üzleti modell szintén nem túl bonyolult:

A különféle meteorológiai szolgáltató cégek komoly beruházások eredményeként tudnak időjárást jósolni, ezért szolgáltatásaikat pénzért kínálják. Egyebek mellett ilyen szolgáltatást - és számukra bevételi forrást - jelentenek az időjárási API-k is. Ezért ezek jellemzően fizetősek.
"Kisemberként", vagyis webprogramozóként mi nem tudunk időjárást jósolni, viszont előfizetve egy a fentiekben leírt időjárási API-ra már létrehozhatunk látványos időjárás előrejelző weboldalakat, mint amilyen például az idokep.hu, vagy a koponyeg.hu, melyek nézettségük okán olyan értékes reklámfelülettel bírnak, aminek köszönhetően busásan megtérül az előfizetés anyagi ráfordítása.
Éppen az idokep.hu oldal bevételeivel is a Magyar oldalak - magyar pénzek című lapunkon korábban már foglalkoztunk.

A REST API-k használata saját weboldalunkon akár jelentős nézettségnövekedést is generálhat, és ezen keresztül komoly bevételi forrást eredményezhet.

Mindezek okán ingyenes meteorológiai API-t nem könnyű találni a neten. Tanulmányi célra azonban az infojegyzet.hu az alábbi lehetőséget kínálja Budapest időjárásának előrejelzésére:

Az időjárási adatokat a weatherapi.com szolgáltatja számunkra. Természetesen az adatok értelmezéséhez első lépéseként itt is érdemes megnézni a JSON formát annak olvashatóvá tételével:

Az adatok értelmezését és felhasználását ezúttal már Önre bízzuk! Tekintse át, vajon

milyen időtartamra ad előrejelzést az API?
időben milyen részletezettségű az előrejelzés?
mi mindent tartalmaz az előrejelzés?
csak időjárási adatok találhatóak az eredmények között?


Napkelte	A nappal hossza ma	Napnyugta
5:45	13:56	19:41

Hasznos érdekesség

Mint fentebb láttuk, az API által visszaadott tartalom áttekintése, emberi értelmezése különösen sok adat esetén meglehetősen nehézkes. Ebben a kihívásban adhat jelentős segítséget az alábbi oldal:

jsonviewer.stack.hu/

A felbukkanó felület megfelelő részébe - vágólapon keresztül - be kell illesztenünk a vizsgálandó JSON kódot, majd a Viewer fülre kattintva már tanulmányozhatjuk is annak struktúráját és tartalmát.

A felületen érdemes lehet kipróbálnunk a Load JSON data gombot is, mely a vágólapról történő beillesztés helyett közvetlenül az API linkjéből tudja áttekinthetően megjeleníteni annak eredményét. Némi korlátozást jelent, hogy ezen funkció valamiért csak http protokollal (is) működő API-k esetén használható, https kezdetű URL-ek esetén panaszkodik.

Kapcsolódó feladatok

1.
A fent bemutatott 6 API végpont mindegyike akkor ismerhető és érthető meg igazán, ha saját klienst készítve hozzájuk megpróbáljuk őket használni. Ezt a fajta tanulást kívánja elősegíteni az API klensek a gyakorlatban című oldal. Nézze át, majd végezze el az ott szereplő feladatokat!

2.

Továbbgondolva az eddigieket beláthattó, hogy akár mi magunk is készítünk mások számára új API-kat. Ez nyilván már lényegesen több tervező munkát igényel, ekképpen jóval izgalmasabb programozói kihívás - szerveroldalon. Az új API eredményei lehetnek véletlenszerűek, számoláson alapulóak, vagy éppen különféle adatforrásokat felhasználóak. Tekintsen rá néhány lehetséges feladatra az API végpontok létrehozása című témában is.

előző oldal

random oldal

következő oldal

Eddig 4 hozzászólás van a témához:

2022-02-22 17:09 Raz Ez egy remek összeállítás, remek gyakorló apikkal!!

2022-02-22 17:39 Admin Köszönöm, Raz :)

2022-03-03 13:24 Szp Szp

React-ben próbáltam az Elvira Api-t, de cors hibát kapok, amikor le akarom tölteni az adatokat fetch-el.

2022-03-04 12:04 Admin Kedves Szp,
mivel jelen oldal látható módon gond nélkül használja az API-t, nyilván nem az API-val van a baj. Jobb ötlet híján arra gondolok, hogy esetleg az ön fejlesztőkörnyezete blokkolhatja valahol a hozzáférést. De hogy hol és miért, ezt csak ön tudja kideríteni.

Új hozzászólás:
E-mail cím:	Erre a címre küldjük ki a hozzászólás jóvá- hagyásához szükséges linket. Az e-mail címet sehol nem tesszük közzé.
Név:	Ez a név fog megjelenni az Ön hozzászólásai mellett.
Mennyi tizenkilenc + öt? Számjegyekkel írja be!	Ez a robotok beírása elleni védelem miatt szükséges ellenőrzés.