A REST API alapvető funkciója ugyanaz, mint az internet böngészése. Az ügyfél az API használatával lép kapcsolatba a szerverrel, amikor erőforrásra van szüksége.
Az API-fejlesztők a kiszolgálóalkalmazás API dokumentációjában elmagyarázzák, hogyan kell az ügyfélnek használnia a REST API-t.
Ezek az általános lépések bármely REST API-híváshoz:
- A kliens kérést küld a szervernek. Az ügyfél követi az API dokumentációját, hogy a kérést a szerver számára érthető módon formázza.
- A szerver hitelesíti az ügyfelet, és megerősíti, hogy az ügyfélnek jogában áll a kérést benyújtani.
- A szerver megkapja a kérést, és belsőleg feldolgozza.
- A szerver választ küld a kliensnek. A válasz olyan információkat tartalmaz, amelyek közlik az ügyféllel, hogy a kérés sikeres volt-e. A válasz tartalmazza az ügyfél által kért információkat is.
A REST API kérés és válasz részletei kissé eltérnek attól függően, hogy az API fejlesztői hogyan tervezik az API-t.
Mit kell tartalmaznia egy REST API kliens kérésnek?
A REST API megköveteli a klienstől, hogy tartalmazzák a kérésben a következő dolgokat:
Egyedi erőforrás azonosító
A szerver minden erőforrást egyedi erőforrás-azonosítókkal azonosít. A REST-szolgáltatások esetében a kiszolgáló általában egy egységes erőforrás-kereső (URL - Uniform Resource Locator) segítségével hajtja végre az erőforrás-azonosítást. Az URL az erőforrás elérési útját adja meg. Az URL hasonló azon webhelyek címéhez, amelyet a böngészőben adunk meg bármely weboldal meglátogatásához. Az URL-t kérés végpontnak is nevezik, és egyértelműen meghatározza a kiszolgáló számára, hogy az ügyfélnek mire van szüksége.
Például egy webshopból le szeretnénk kérni API-n keresztül az összes terméket, amihez a következő URL-t használjuk: http://webshop.com/termkek
Metódus
A HTTP metódus közli a szerverrel, hogy mit kell tennie az erőforrással. Nézzük meg a legáltalánosabb HTTP metódusokat:
GET
A kliensek a GET metódus segítségével érik el az erőforrásokat, amelyek a kiszolgáló megadott URL-címén találhatók. Gyorsítótárazhatják a GET kéréseket, és paramétereket küldhetnek a RESTful API kérésben, hogy utasítsák a szervert az adatok szűrésére a küldés előtt.
Előző példánknál maradva, amikor lekértük a termékeket, akkor azt egy GET metódussal tudtuk megtenni.
POST
A kliensek a POST metódus segítségével küldik el az adatokat a szervernek. Tartalmazza az adatot a kéréssel együtt.
Például amikor egy terméket felvisznek a webshopba, akkor azt egy POST metódussal tudják megtenni.
PUT
A kliensek a PUT metódus segítségével tudják módosítani a szerveren meglévő erőforrásokat.
Például ha módosítani szeretnénk egy terméket a webshopban, akkor a PUT metódust kell használni hozzá.
DELETE
A kliensek a DELETE metódus segítségével törölhetnek egy erőforrást.
Például termék törléséhez a webshopból a DELETE metódust használják.
HTTP fejlécek
A kérések fejlécei a kliens és a szerver közötti metaadatok. Például a kérés fejléce jelzi a kérés és a válasz formátumát, információt ad a kérés állapotáról stb.
Adat
A REST API kérések tartalmazhatnak adatokat a POST, PUT és más HTTP metódusok sikeres működéséhez.
A JSON (JavaScript Object Notation) egy általános formátum az adatok REST API-n keresztül történő küldéséhez és kéréséhez.
De felmerül a kérdés, hogy mi az a JSON?
A JSON egy kulcs-érték párosokból felépülő objektum. Az előző webshopos példánál maradva egy termék a következőképpen nézhet ki JSON-ban:
Ezt a JSON formázott szöveget pedig elhelyezhetjük az API kérés törzsében.
Paraméterek
A RESTful API kérések tartalmazhatnak olyan paramétereket, amelyek további részleteket adnak a szervernek a teendőkről. Az alábbiakban néhány különböző típusú paraméter található:
Útvonal (path) paraméter amit az URL-ben helyezünk el. Tegyük fel nekem a webshopból szükségem lenne az 1-es azonosítóval ellátott termék részleteire, akkor a következő URL-t kellene megadnom: http://webshop.com/termkek/1
Lékérdezés (query) paraméter, ami hasonlít az útvonal paraméterhez, de segítségével több feltételt is megadhatunk, amivel szűkíthetjük a lekérdezést a szerverről. Például szeretném megkapni a férfi ruházatok közül az M-es méretű, fekete pólókat, akkor az a következőképpen nézne ki: http://webshop.com/termkek/ferfi-ruhazatok?kategoria=polo&meret=m&szin=fekete
Mint láthatjuk a ferfi-ruházatok rész után következő kérdőjel után sorolhatjuk fel a további paramétereket, & jellel elválaszva egymástól őket.
Mit kell tartalmaznia egy REST API szerver válasznak?
A REST alapelvek megkövetelik, hogy a szerver válasza a következő fő összetevőket tartalmazza:
Állapotsor
Az állapotsor egy háromjegyű állapotkódot tartalmaz, amely a kérés sikerességét vagy sikertelenségét jelzi. Például a 2XX kód sikert jelez, de a 4XX és 5XX kód hibát jelez. A 3XX kódok az URL-átirányítást jelzik. Nézzük meg a főbb állapotkódokat:
A válasz törzs tartalmazza az erőforrás-ábrázolást. A szerver a kérés fejlécek tartalma alapján választ ki egy megfelelő megjelenítési formátumot. Például a kliensek JSON formátumban kérhetnek információkat.
Fejlécek
A válasz fejléceket vagy metaadatokat is tartalmazhat. Több kontextust biztosítanak a válaszról, és olyan információkat tartalmaznak, mint a szerver, a kódolás, a dátum és a tartalom típusa.
Összegzés
Összefoglalva tehát, a REST egyfajta adatátvitel, amely a HTTP protokoll architektúrájára épül. Lehetővé teszi az adatok egyszerű küldését és lekérését kliens és szerver között.