< REST

REST API

Szerző: Sallai András

Copyright © Sallai András, 2021, 2022

Licenc: CC Attribution-Share Alike 4.0 International

Web: https://szit.hu

REST-ről

reprezentatív állapotátvitel

Roy Fielding 2000-ben mutatta be.

A REST egy szoftverarchitektúra-stílus.

Megszorítások, aminek meg kell feleljen egy REST alkalmazás:

kliens-szerver

URL-n keresztül elérhető

állapotmentes

rétegelt rendszer

gyorstárazható

egységes interfész köti össze a szervert és a klienst

igényelt kód - a szerver kódokat ad át a kliensnek futtatásra (JavaScript)

Ha egy alkalmazás megfelel ezeknek a követelményeknek, akkor azt RESTful alkalmazásnak nevezzük.

Ha egy fejlesztő ért mind a frontend, mind a backend fejlesztéshez őt nevezzük Full Stack fejlesztőnek. Az ilyen fejlesztő tehát tud külön Frontendet fejleszteni, de Backendet is.

Néhol használják a Full Stack szót a Frontend és Backend együttes használatára. Ebben az esetben is arról van szó, hogy a két rész között HTTP protokollt használunk. HTTP nélkül nem beszélhetünk Full Stack technológiáról.

Új API technológiák:

GraphQL

gRPC

A REST API előtt, a webszolgáltatások hálózaton keresztüli kommunikációjához a SOAP protokollt használták, ami XML alapú, ami más alkalmazásprotokollokat használnak, például távoli eljáráshívás.

REST API

A REST API HTTP protokollal:

az API HTTP protokollon teszi elérhetővé az adatokat

az erőforráson CRUD műveletek elvégezhetők

HTTP módok használata: GET, POST, PUT/PATCH, DELETE

Az összeállított URL-k végeit, végpontoknak nevezzük. A végpontokat tetszőlegesen állítjuk össze.

Példa végpontokra:

GET	/dolgozok	– az összes elem lekérése
GET	/dolgozok/janos	– egy elem lekérése
POST	/dolgozok	– beszúrás, új dolgozó beszúrása
PUT	/dolgozok/janos	– janos adatainak frissítése
PATCH	/dolgozok/janos	– janos valamely tulajdonságát változtatjuk
DELETE	/dolgozok	– az összes törlése
DELETE /dolgozok/janos	– janos törlése

A végpontok CRUD műveleteket valósítanak meg. Az egyes CRUD műveletekhez a következő HTTP metódusokat szoktuk rendelni:

CRUD művelet Metódus Végpontpélda
------------------------------------
create	POST	/dolgozok
read	GET	/dolgozok[/id]
update	PUT	/dolgozok/id
update	PATCH	/dolgozok/id
delete	DELETE	/dolgozok[/id]

Végpont

A végpont a kérelem benyújtásához használt URL. Például:

http://zold.lan/dolgozok

A http://zold.lan/dolgozok végpont a dolgozók halmazának erőforrását szolgálja ki számunkra.

Előfordul, hogy ugyanahhoz az erőforráshoz többféle végponton hozzáférhetünk:

http://zold.lan/dolgozok
http://zold.lan/api/dolgozok
http://zold.lan/api/v2/dolgozok
http://zold.lan/employees

Egyazon végpont különböző erőforrásokat szolgáltathat, ha például szűrök, keresek rendezek. A végpont a http://zold.lan/dolgozok.

http://zold.lan/dolgozok
http://zold.lan/dolgozok?search=Emese
http://zold.lan/dolgozok?sort=jutalom
http://zold.lan/dolgozok?filter=Szeged

Szoftverek REST API-hoz

A REST API teszteléséhez erre a célra kialakított kliens programot használunk. Egyik elterjedt kliens a Postman, amit itt ajánlunk az Insomnia.

https://httpie.io/ (kliens)

https://insomnia.rest/ (kliens)

https://www.thunderclient.io/ (kliens)

https://www.postman.com/ (kliens)

https://github.com/frigus02/RESTer (kliens; böngésző bővítmény)

https://swagger.io/ (tervező, dokumentáció készítő)

https://github.com/swagger-api/swagger-editor (tervező)

httpie

A httpie telepíthető npm paranccsal, de Linuxon linuxos csomag is rendelkezésre áll. Telepítés után egy http parancsot kapunk.

Teszteléshez írjuk be:

http get http://localhost/valami/

Apache szerver esetén, ha csak ennyit írunk:

http://localhost/valami

Egy átirányítás történik a következő címre:

http://localhost/valami

Ez jól látszik a http parancs kimenetében:

http get http://localhost/valami/

A kimenet ehhez hasonló:

HTTP/1.1 301 Moved Permanently
Connection: Keep-Alive
Content-Length: 310
Content-Type: text/html; charset=iso-8859-1
Date: Fri, 22 Oct 2021 20:43:09 GMT
Keep-Alive: timeout=5, max=100
Location: http://localhost/valami/
Server: Apache/2.4.51 (Debian)
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html><head>
<title>301 Moved Permanently</title>
</head><body>
<h1>Moved Permanently</h1>
<p>The document has moved <a href="http://localhost/valami/">here</a>.</p>
<hr>
<address>Apache/2.4.51 (Debian) Server at localhost Port 80</address>
</body></html>

Ha „/” a végére kerül, akkor kimenet:

HTTP/1.1 200 OK
Connection: Keep-Alive
Content-Length: 9
Content-Type: text/html; charset=UTF-8
Date: Fri, 22 Oct 2021 20:44:30 GMT
Keep-Alive: timeout=5, max=100
Server: Apache/2.4.51 (Debian)
Valami weblap

Ha localhost-t használunk rövidíthetünk:

http :8000
http :/valami

Alapértelmezett a GET:

http zold.lan

Ha van adat, akkor POST

http zold.lan valami=érték

A ? előtt mindig \ jel szükséges:

http get http://localhost:8000/index.php\?products

JSON adatok átadása:

http post http://localhost:8000/index.php\?products < newProduct.json

Insomnia

Beszerzés

https://insomnia.rest/

Windowsra létezik portable verzió is:

Insomnia.Core-2021.5.3-portable.exe

Debian GNU/Linux 11-re az Ubuntus verzió nem telepszik. Használjuk helyette a .tar.gz kiterjesztésű fájl. Ebben találunk egy futtatható binárist.

Használat

Jobb oldalon van egy „Create” gomb.

Create > Request Collection

Ez előugró ablakban adjunk a kollekciónak nevet. Például:

app01

Kattintsunk a „Create” gombra.

Baloldalon, a + ikonra kattintva hozzunk létre egy új könyvtárat:

New Folder Shift+Ctrl+N

Az „app01” könyvtár sávjába vitt egér kurzor megjelenít egy legördülő listadobozt. Erre kattintva, az előugró menüből válassza a „New Request” lehetőséget, egy kérés létrehozásra. Az előugró ablakban például:

get employees

HATEOAS

A HATEOAS a Hypermedia as the Engine of Application State rövidítése.

A HATEOAS szerint REST API-ba érdemes olyan linkeket elhelyezni, amelyek segítségével az alkalmazás önfelfedező lesz.

Ha egy kliens lekért valamit, azt is látja, hogyan tud továbbmenni.

{ "dolgozo": { "azonosito": "BD132", "nev": "Bari Emese", "szuletes": "1995-03-04", "links": { "beosztas": "dolgozok/BD132/beosztas", "fizetes": "dolgozok/BD132/fizetes" } } }

REST API leírás

Végpontleírás példa:

Végpont	Metódus	CRUD	Azonosítás	Siker	Kudarc	Leírás
/api/employees	GET	READ	nem	200 OK	400 Bad Request 404 Not found	Összes dolgozó lekérése
/api/employees	POST	CREATE	igen	201 Created	400 Bad Request 404 Not found	Új dolgozó hozzáadása
/api/employees/{id}	PUT	UPDATE	igen	200 OK	400 Bad Request 404 Not found	Dolgozó frissítése

Linkek

https://restfulapi.net/ (2021)

https://restfulapi.net/hateoas/

https://restfulapi.net/rest-api-design-tutorial-with-example/

https://restfulapi.net/security-essentials/

https://swagger.io/ (2021)

Egy JSON kiszolgáló példa:

https://jsonplaceholder.typicode.com/ (2022)

https://jsonplaceholder.typicode.com/users/ (2022)

https://gorest.co.in/ (2022)

https://reqres.in/ (2022)

API tervezés:

https://docs.microsoft.com/hu-hu/azure/architecture/best-practices/api-design

Azonosítás:

https://auth0.com/docs (2021)