Merge pull request #83 from bmeviauac01/hf2024webapi

HF4: revamp, Exercise 2 addition, new Exercise 3

docs/hu/homework/rest/index.md

@@ -1,9 +1,6 @@
 # Feladat: REST API Web API technológiával
 
-!!! important "FIGYELEM"
-    2024-re még nem végleges!
-
-A ASP.NET Core REST API házi feladat, a teljesítéssel **2 pont és 3 iMsc pont** szerezhető.
+A házi feladat teljesítésével **4 pont és 3 iMsc pont** szerezhető.
 
 GitHub Classroom segítségével hozz létre magadnak egy repository-t. A **meghívó URL-t Moodle-ben találod**. Klónozd le az így elkészült repository-t. Ez tartalmazni fogja a megoldás elvárt szerkezetét. A feladatok elkészítése után kommitold és pushold a megoldásod.
 
@@ -13,7 +10,7 @@ A megoldáshoz szükséges szoftvereket és eszközöket lásd [itt](../index.md
 
 Első lépésként a gyökérben található `neptun.txt` fájlba írd bele a Neptun kódodat!
 
-## Feladat 1: Termék műveletek (2 pluszpont)
+## Feladat 1: Egyszerű lekérdezés és OpenAPI dokumentáció (2 pont)
 
 A létrehozott és klónozott repository-ban megtalálható a kiinduló kód váz. Nyisd meg Visual Studio-val és indítsd el. Egy konzol alkalmazásnak kell elindulnia, amely hosztolja a web alkalmazást. Próbáld ki (miközben fut a program): böngészőben nyisd meg a <http://localhost:5000/api/product> oldalt, ahol a termékek listáját kell lásd JSON formában.
 
@@ -25,14 +22,46 @@ Nézd meg a rendelkezésre álló kódot.
 
 Feladatok:
 
+### Egyszerű lekérdezés
+
 1. A `DAL.ProductRepository` osztályban a `Neptun` nevű mező értékében cseréld le a Neptun kódod. A string értéke a Neptun kódod 6 karaktere legyen.
 
     !!! warning "FONTOS"
         Az így módosított adatokról kell képernyőképet készíteni, így ez a lépés fontos.
 
 1. Készíts egy olyan API végpontot, amivel ellenőrizhető, hogy létezik-e egy adott id-jú termék. A lekérdezéshez egy `HEAD` típusú HTTP kérést fogunk küldeni a `/api/product/{id}` URL-re. A válasz HTTP 200 vagy 404 legyen (extra tartalom/body nélkül, csak a válaszkód szükséges).
 
-1. Készíts egy olyan API végpontot, ami egy terméket (`Product`) ad vissza az id-ja alapján; a kérés `GET` típusú legyen a `/api/product/{id}` címre, és a válasz vagy 200 legyen az adattal, vagy 404, ha nincs ilyen elem.
+### OpenAPI dokumentáció
+
+Az OpenAPI (korábbi nevén Swagger) egy REST API dokumentációs eszköz. Célja hasonló a Web Service-ek esetében használt WSDL-hez: leírni az API szolgáltatásait egy standardizált formában. A korábbi feladatok megoldása után készíts [OpenAPI specifikációt és dokumentációt](https://docs.microsoft.com/en-us/aspnet/core/tutorials/web-api-help-pages-using-swagger) a REST API leírásához.
+
+1. A megoldáshoz kövesd a Microsoft hivatalos dokumentációját: <https://docs.microsoft.com/en-us/aspnet/core/tutorials/getting-started-with-swashbuckle>
+
+    - Mindenképpen a **Swashbuckle** opciót használd.
+    - A `swagger.json`-t az alkalmazás maga generálja (nem kézzel kell megírnod), és a `/swagger/v1/swagger.json` címen legyen elérhető.
+    - Állítsd be a _Swagger UI_-t is, ez a `/neptun` címen legyen elérhető. Ezt a `UseSwaggerUI` beállításánál a `RoutePrefix` konfigurálásával fogod tudni elérni. A saját Neptun kódod legyen a prefix **csupa kisbetűvel**.
+    - (A "Customize and extend" résszel és egyéb testreszabással nem kell foglalkoznod.)
+
+1. Indítsd el a webalkalmazást, és nézd meg a `swagger.json`-t <http://localhost:5000/swagger/v1/swagger.json> címen, és próbáld ki a SwaggerUI-t a <http://localhost:5000/neptun> címen.
+
+1. Próbáld ki a SwaggerUI "Try it out" szolgáltatását: tényleg kiküldi a kérést a webalkalmazásnak, és látod a valódi választ.
+
+    ![SwaggerUI Try it out](swaggerui-try.png)
+
+1. Készítd el azt az API végpontot, ami vissza is adja a kívánt terméket (`Product`) az id-ja alapján; a kérés `GET` típusú legyen a `/api/product/{id}` címre, és a válasz vagy 200 legyen az adattal, vagy 404, ha nincs ilyen elem. Ellenőrizd a SwaggerUI segítségével.
+
+!!! example "BEADANDÓ"
+    A módosított forráskódot töltsd fel. Ügyelj rá, hogy a `csproj` fájl is módosult a hozzáadott NuGet csomaggal!
+
+    Készíts egy képernyőképet a böngészőben megjelenő Swagger UI-ról. Ügyelj rá, hogy az URL-ben látható legyen, hogy a SwaggerUI-t a `/neptun` címen szolgálja ki a rendszer a saját Neptun kódoddal. A képet `f2.png` néven mentsd el és add be a megoldásod részeként!
+
+## Feladat 2: Termék műveletek (2 pont)
+
+A termékekkel kapcsolatos leggyakoribb adatbázisműveletek az új beszúrása, meglévő termék lekérdezése, módosítása vagy törlése, vagyis a CRUD (create, read, update és delete) műveletek. Ezekhez dedikált végpontokat készítünk, amiken keresztül a műveletek végrehajtását el tudja végezni az API használója. Ebben a feladatban a leggyakoribb végpontokat kell implementálni a már meglévő lekérdezés mellé.
+
+1. Készíts egy olyan API végpontot, ami beszúr egy új terméket (`Product`) az id-ja alapján; a kérés `POST` típusú legyen a `/api/product` címre, a kérés törzsében várja az új `Product` értéket, és a válasz vagy 201 legyen, vagy 419, ha már van ilyen elem.
+
+1. Készíts egy olyan API végpontot, ami módosít egy terméket (`Product`) az id-ja alapján; a kérés `PUT` típusú legyen a `/api/product/{id}` címre, a kérés törzsében várja a változtatott `Product` értéket, és a válasz vagy 204 legyen tartalom nélkül, vagy 404, ha nincs ilyen elem.
 
 1. Készíts egy olyan API végpontot, ami töröl egy terméket (`Product`) az id-ja alapján; a kérés `DELETE` típusú legyen a `/api/product/{id}` címre, és a válasz vagy 204 legyen tartalom nélkül, vagy 404, ha nincs ilyen elem.
 
@@ -46,29 +75,29 @@ Feladatok:
 !!! example "BEADANDÓ"
     A módosított forráskódot töltsd fel.
 
-    Emellett készíts egy képernyőképet Postman-ből (vagy más teszteléshez használt eszközből), amely egy sikeres termék lekérés eredményét mutatja. A képen legyen látható a kérés és a válasz minden részlete (kérés típusa, URL, válasz kódja, válasz tartalma). A válaszban a névben szerepelnie kell a **Neptun kódodnak**. A képet `f1.png` néven mentsd el és add be a megoldásod részeként!
+    Emellett készíts egy képernyőképet Postman-ből (vagy más teszteléshez használt eszközből), amely egy sikeres termék lekérés eredményét mutatja. A képen legyen látható a kérés és a válasz minden részlete (kérés típusa, URL, válasz kódja, válasz tartalma). A válaszban a névben szerepelnie kell a **Neptun kódodnak**. A képet `f2.png` néven mentsd el és add be a megoldásod részeként!
 
-## Feladat 2: OpenAPI dokumentáció (2 iMsc pont)
 
-!!! note ""
-    Az iMsc pont megszerzésére az első feladat megoldásával együtt van lehetőség.
 
-Az OpenAPI (korábbi nevén Swagger) egy REST API dokumentációs eszköz. Célja hasonló a Web Service-ek esetében használt WSDL-hez: leírni az API szolgáltatásait egy standardizált formában. A korábbi feladatok megoldása után készíts [OpenAPI specifikációt és dokumentációt](https://docs.microsoft.com/en-us/aspnet/core/tutorials/web-api-help-pages-using-swagger) a REST API leírásához.
+## Feladat 3: Termék részleges frissítése (3 iMsc pont)
 
-1. A megoldáshoz kövesd a Microsoft hivatalos dokumentációját: <https://docs.microsoft.com/en-us/aspnet/core/tutorials/getting-started-with-swashbuckle>
+!!! note ""
+    Az iMsc pont megszerzésére az első két feladat megoldásával együtt van lehetőség.
 
-    - Mindenképpen a **Swashbuckle** opciót használd.
-    - A `swagger.json`-t az alkalmazás maga generálja (nem kézzel kell megírnod), és a `/swagger/v1/swagger.json` címen legyen elérhető.
-    - Állítsd be a _Swagger UI_-t is, ez a `/neptun` címen legyen elérhető. Ezt a `UseSwaggerUI` beállításánál a `RoutePrefix` konfigurálásával fogod tudni elérni. A saját Neptun kódod legyen a prefix **csupa kisbetűvel**.
-    - (A "Customize and extend" résszel és egyéb testreszabással nem kell foglalkoznod.)
+A termékek módosítása esetén az eddig használt `PUT` hívásnak számos hátránya van. A `PUT` a teljes erőforrás frissítésére lett kitalálva, azaz egy termék módosításához a teljes terméket el kell küldeni. Ez egyrészt kevéssé hatékony (például hálózaton le kell kérni és átküldeni minden meglévő tulajdonságát, akármilyen nagyok is azok), illetve ezek feldolgozása is plusz feladatokat jelenthet. A `PATCH` ige arra lett kitalálva, hogy részleges frissítési lehetőséget biztosítson, azaz elég legyen elküldeni azokat a tulajdonságokat amiket módosítani szeretnénk.
 
-1. Indítsd el a webalkalmazást, és nézd meg a `swagger.json`-t <http://localhost:5000/swagger/v1/swagger.json> címen, és próbáld ki a SwaggerUI-t a <http://localhost:5000/neptun> címen.
+Ebben a feladatban létre kell hoznod egy végpontot, ami biztosítja a termékek részleges frissítését:
 
-1. Próbáld ki a SwaggerUI "Try it out" szolgáltatását: tényleg kiküldi a kérést a webalkalmazásnak, és látod a valódi választ.
+1. A kérés `PATCH` típusú legyen a `/api/product/{id}` címre, és a válasz vagy 204 legyen, ha sikerül, vagy 404, ha nincs ilyen elem.
 
-    ![SwaggerUI Try it out](swaggerui-try.png)
+1. A `ProductController` osztályban valósítsd meg a végpontot, ami elvégzi a részleges frissítést.
+A végpont által kapott paraméter típusa `JsonPatchDocument` erősen típusos változata legyen.
+Tesztelés során figyelj rá, hogy csak a küldött értékek változzanak meg (például, ha nincs felküldött objektumban raktárkészlet, az ne változzon).
+
+!!! tip "JsonPatchDocument"
+    A `JsonPatchDocument` az ASP.NET Core által nyújtott osztály és tartozik hozzá beépített mechanizmus is.
 
 !!! example "BEADANDÓ"
-    A módosított forráskódot töltsd fel. Ügyelj rá, hogy a `csproj` fájl is módosult a hozzáadott NuGet csomaggal!
+    A módosított forráskódot töltsd fel.
 
-    Készíts egy képernyőképet a böngészőben megjelenő Swagger UI-ról. Ügyelj rá, hogy az URL-ben látható legyen, hogy a SwaggerUI-t a `/neptun` címen szolgálja ki a rendszer a saját Neptun kódoddal. A képet `f2.png` néven mentsd el és add be a megoldásod részeként!
+    Emellett készíts egy képernyőképet Postman-ből (vagy más teszteléshez használt eszközből), amely egy sikeres részleges módosítás eredményét mutatja. A képen legyen látható a kérés és a válasz minden részlete (kérés típusa, URL, válasz kódja, válasz tartalma). A válaszban a névben szerepelnie kell a **Neptun kódodnak**. A képet `f3.png` néven mentsd el és add be a megoldásod részeként!