[[oktatas:web:rest_api|< REST API]] ====== REST API ====== * **Szerző:** Sallai András * Copyright (c) 2021, Sallai András * Szerkesztve: 2021, 2022, 2024 * Licenc: [[https://creativecommons.org/licenses/by-sa/4.0/|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: * [[https://graphql.org/|GraphQL]] * [[https://grpc.io/|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. {{:oktatas:web:rest:restful_struktura.png|}} ===== 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 {{:oktatas:web:rest:restful.png|}} 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] {{:oktatas:web:rest:full_stack.png|}} ===== Visszatérési értékek ===== * https://www.rfc-editor.org/rfc/rfc7231#section-4.3 ^ A GET ^^^ | GET | 200 (OK) || | GET | 404 Bad request | | | GET | 404 (Not found) || ^ A POST ^^^ | POST | 201 (Created) | siker, a választ sikerleírást tartalmaz | | POST | 206 (Partial Content | | | POST | 304 (Not Modified | | | POST | 416 (Range Not Satisfiable) | | ^ A PUT ^^^ | PUT | 200 (OK) | siker, a választ sikerleírást tartalmaz | | PUT | 204 (No Content) | Ha, ok de nincs a válaszban tartalom | | PUT | 409 (Conflict) | | | PUT | 415 (Unsupported Media Type | | ^ A DELETE válaszai ^^^ | DELETE | 202 (Accepted) | sikeres alkalmazás | | DELETE | 204 (No Content) | ha nem kell tovább információ | | DELETE | 200 (OK) | ha válasz állapotleírást tartalmaz | ===== 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ő) * https://boomerangapi.com/ (kliens) * [[https://chrome.google.com/webstore/detail/boomerang-soap-rest-clien/eipdnjedkpcnlmmdfdkgfpljanehloah|https://chrome.google.com/webstore/]] ===== 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) 301 Moved Permanently

Moved Permanently

The document has moved here.

Apache/2.4.51 (Debian) Server at localhost Port 80
 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 ==== Bearer token ==== http post http://localhost:8080/api/checkToken -A bearer -a eyJhbG... Vegyünk fel egy felhasználót: http post http://localhost:8080/api/registry name='dani' password='titok' Lépjünk be a felhasználóval: http post http://localhost:8080/api/login name='dani' password='titok' Védett útvonalak tesztje: http post http://localhost:8080/api/employees name='Pista' city='Pécs' salary=398 -A bearer -a eyJhbGc... http -A bearer -a eyJhbGc... post http://localhost:8080/api/employees name='Pista' city='Pécs' salary=398 ===== 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) 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) * https://dog.ceo/ (2022) API tervezés: * https://docs.microsoft.com/hu-hu/azure/architecture/best-practices/api-design Azonosítás: * https://auth0.com/docs (2021)