szit

Ez az oldal csak olvasható. Megtekintheted a forrását, de nem változtathatod meg. Ha úgy gondolod, hogy ez helytelen, kérdezd az Adminisztrátorokat!
[[oktatas:web:rest_api|< REST API]]

====== REST API ======

  * **Szerző:** Sallai András
  * Copyright (c) 2021, Sallai András
  * Szerkesztve: 2021, 2022, 2024, 2025
  * 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:
<code>
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
</code>


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

<code>
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]
</code>

{{: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ó:
<code>
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>

</code>

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

<code>
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
</code>


Ha localhost-t használunk rövidíthetünk:
<code>
http :8000
http :/valami
</code>


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 ====

<code>
http post http://localhost:8080/api/checkToken 
-A bearer -a eyJhbG...
</code>


Vegyünk fel egy felhasználót:
<code>
http post http://localhost:8080/api/registry
name='dani' password='titok'
</code>

Lépjünk be a felhasználóval:
<code>
http post http://localhost:8080/api/login
name='dani' password='titok'
</code>

Védett útvonalak tesztje:

<code>
http post http://localhost:8080/api/employees 
name='Pista' city='Pécs' salary=398 
-A bearer -a eyJhbGc...
</code>


<code>
http -A bearer -a eyJhbGc... post 
http://localhost:8080/api/employees 
name='Pista' city='Pécs' salary=398 
</code>

===== 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.

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


===== 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
  * https://learn.microsoft.com/hu-hu/azure/architecture/best-practices/api-design
  * https://restfulapi.net/rest-api-design-tutorial-with-example/
  * https://upsun.com/blog/restful-api-design-principles/

Azonosítás:
  * https://auth0.com/docs (2021)

Könyvek
  * https://github.com/tdonker/REST-API-books