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:

1. 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.
2. A szerver hitelesíti az ügyfelet, és megerősíti, hogy az ügyfélnek jogában áll a kérést benyújtani.
3. A szerver megkapja a kérést, és belsőleg feldolgozza.
4. 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.