A RESTful API tervezésben a PUT és a PATCH két HTTP metódus, amelyeket a szerveren lévő erőforrások frissítésére használnak. A PUT és PATCH közötti különbség REST APIs esetén abban rejlik, hogy hogyan végzik el a frissítéseket és mely forgatókönyvekben alkalmazhatók leginkább. Mindkét metódus meglévő adatok módosítására szolgál, de a PUT és PATCH közötti különbség megértése REST APIs-ben segít a fejlesztőknek a legmegfelelőbb választást meghozni a frissítés jellegétől függően. Ebben a bejegyzésben a PUT és PATCH közötti különbséget vizsgáljuk meg REST APIs kontextusában, különös tekintettel a PATCH vs frissítés REST vitára, a használati esetekre és praktikus útmutatást adunk arra, hogy melyik metódust válasszuk az egyes helyzetekben.
Mi van a PUT-ban az REST APIs-ben?
Ahhoz, hogy megértsük a PUT és PATCH közötti különbséget az REST APIs-ben, először azt kell tudnunk, hogy mi is a PUT valójában. Ennek alapján 9.6. szakasz RFC 2616, a PUT metódus az REST API kérésekben azt kéri, hogy a mellékelt entitást a megadott Request-URI alatt tároljuk.
Ha a Request-URI egy már létező erőforrásra hivatkozik, az adott entitást az origin szerveren tárolt verzió módosított változataként kell kezelni. Ha a Request-URI nem mutat egy meglévő erőforrásra, és az URI alkalmas arra, hogy a kérést küldő felhasználói ügynök új erőforrásként definiálja, az origin szerver létrehozhatja az adott URI-hoz tartozó erőforrást.
Más szóval, a PUT metódus a szerveren egy teljes erőforrás frissítésére szolgál. Ez teszi a PUT-ot egy teljesebb frissítéssé, amelyet akkor használnak, ha az erőforrás teljes cseréje szükséges.
A PUT módszer tehát az alábbi esetekben a legjobb választás:
- Egy teljes erőforrás frissítése (például egy felhasználói profil összes adatának új információkkal való frissítése).
- Teljes elem vagy bejegyzés cseréje.
- Amikor az erőforrás identitása egyértelmű, és az adatait teljes mértékben frissíteni kell.
Olyan rendszerekben, mint a Elasticsearch, az idempotens műveletek szükségesek az adatkonzisztencia biztosításához. Például egy dokumentum frissítése az Elasticsearch-ben PUT-tal garantálja, hogy ugyanez a kérés ismét végrehajtható anélkül, hogy nem kívánt mellékhatások keletkezzenek.
Mi az a PATCH az REST APIs-ben?
Most már, hogy áttekintettük a PUT metódust az REST APIs-ben, nézzük meg, hogy mit jelent a PATCH az REST APIs-ben, és hogyan működik, mielőtt összehasonlítanánk a PUT és PATCH metódusokat az REST APIs-ben. Ahogy azt definiálták RFC 5789, a PATCH metódus az REST API kérésben arra utasítja a rendszert, hogy a kérés entitásában leírt módosítások egy halmazát alkalmazza a Request-URI által azonosított erőforrásra.
Ez összhangban van a PUT és PATCH REST API megkülönböztetéssel, ahol csak a módosítandó adatokat küldöd el, és a szerver ezeket a változásokat az meglévő erőforrásra alkalmazza anélkül, hogy az egész erőforrást felülírná. A fejlesztők gyakran patcheket hoznak létre az ilyen lépcsőzetes módosítások reprezentálásához, így biztosítva a minimális adatforgalmat és a hatékony frissítéseket.
Ezért a PATCH metódus az REST API-ben jobban megfelel az alábbi felhasználási eseteknek:
- Egy erőforrás csak néhány mezőjének frissítése (például egy felhasználó e-mail-címének vagy telefonszámának módosítása). Egy PATCH API példában csak az új e-mail-t küldené el, a többi mező pedig változatlan maradna.
- Teljesítmény javítása az adatforgalom csökkentésével.
- Amikor egy erőforrást fokozatosan szeretnél frissíteni, nem pedig teljesen helyettesíteni.
- Készíts javításokat, hogy elkülönítsd az egyes mező módosításokat, például egy felhasználó e-mail-címének változtatását, anélkül hogy más adatokat érintene.
Platformokhoz, mint például fejléc nélküli CMS amely gyakran összetett tartalomstruktúrákat kezel, a PATCH használata kisebb frissítésekhez - például egy mező módosításához - csökkentheti a szerver terhelését és javíthatja a teljesítményt.
E két módszer ismeretében már van képed arra, hogy megértsd a PUT és PATCH közötti különbséget az REST APIs-ben. Azonban mielőtt rátérnénk a PUT vs PATCH összehasonlítására az REST APIs-ben, beszélnünk kell az idempotencia tulajdonságról ezekben a módszerekben.
Idempotencia a PUT és a PATCH között a REST API-kban
Az REST APIs-ben az idempotencia egy operáció azon tulajdonságát jelenti, amely azt biztosítja, hogy amikor ugyanazokkal a bemenetekkel többször ismételted meg, az eredmény azonos lesz. Ez azt jelenti, hogy ugyanaz a kérés többszöri küldése ugyanolyan hatást kell, hogy gyakoroljon a szerveren, függetlenül attól, hogy hányszor hajtód végre. Ez fontos a stabilitás és kiszámíthatóság biztosításához egy API-ben. De hogyan kapcsolódik ez a PUT és PATCH közötti különbséghez az REST API-ben?
PUT módszer és idempotencia
A PUT módszer az REST API-ben mindig idempotens, mert úgy van kialakítva, hogy az erőforrást egy megadott URI-ban teljes egészében helyettesítse a kérésben található adatokkal. Más szóval, ha többször végrehajtsz egy PUT kérést ugyanazzal az erőforrás-adattal, az eredmény mindig azonos lesz.
Miért idempotens a PUT? Amikor PUT kérést küldöl, lényegében azt mondod a szervernek: "Ez az erőforrás pontos és teljes állapota, amit szeretnék." Akár egyszer, akár többszörösen küldsz PUT kérést, az eredményül kapott erőforrás mindig azonos lesz.
Például vegyünk egy olyan esetet, amikor egy felhasználó e-mail címét frissítesz. Ha többször küldöl ugyanazt a PUT kérést, az eredmény nem változik, mert az erőforrást minden alkalommal ugyanazokkal az adatokkal helyettesítik.
Példa:
| PUT /users/1{"username": "john_doe","email": "[email protected]"} |
Ha ezt a kérést többször küldöl el, az eredmény mindig ugyanaz lesz:
| {"felhasználónév": "john_doe","e-mail": "[email protected]"} |
Még akkor sem, ha a felhasználó adata már ilyen, a kérés újra küldése nem változtat semmit. Ugyanazokkal az adatokkal helyettesíti az adatokat, így a kérés hatása ugyanaz marad, függetlenül attól, hogy hányszor ismételted meg. Ez teszi a PUT-ot idempotensné.
PATCH módszer és idempotencia
A PATCH módszer az REST API-ben általában szintén idempotens, de nagyobb rugalmassággal. Amikor patch-eket hozol létre, biztosítsd, hogy az operációk idempotensek legyenek (például érték beállítása), hogy elkerüld az ismételt kérések nem szándékos mellékhatásait. A PATCH idempotenciája attól függ, hogy az operáció és az érintett adatok hogyan viselkednek.
Miért idempotens a PATCH? PATCH kérések esetén az idempotencia azt jelenti, hogy ugyanez a patch többszöri alkalmazása ugyanerre az eredményre vezet. Ez akkor igaz, ha a patch alkalmazása nem okoz további mellékhatásokat vagy módosításokat az ismételt alkalmazás során. Ha ugyanazt a patch-et ismételten alkalmazod ugyanazokkal az adatokkal, az eredmény az első alkalmazás után már nem változik.
Például, ha csak egy felhasználó e-mail címét frissítesz, a ugyanez a PATCH kérés ismételt küldése nem változtatja meg az eredményt az első alkalommal, még akkor sem, ha a kérést többször küldöd el. A felhasználó e-mail címe ugyanaz marad, és az erőforrás állapota nem változik.
PATCH API Példa:
| PATCH /users/1{"email": "[email protected]"} |
Ha az e-mail már [email protected] volt, akkor ennek a PATCH-nek az újbóli alkalmazása nem fog változást eredményezni, így idempotens lesz.
Azonban a PATCH bizonyos esetekben nem-idempotens is lehet. Például, ha egy PATCH operáció egy számlálót módosít vagy elemeket ad egy listához (például egy szám inkrementálása vagy egy tömbhez fűzése), ugyanez a PATCH ismételt alkalmazása különböző eredményekhez vezethet. Ez megsértené az idempotencia tulajdonságot.
Nem-idempotens API REST PATCH Példa:
| PATCH /counter/1{"increment": 1} |
Ha ezt a PATCH-et ismételten alkalmazod, a számláló folyamatosan nőni fog, különböző értékeket eredményezve minden egyes alkalommal. Ez nem idempotens, mert az eredmény minden alkalmazással megváltozik.
Most, hogy ismered az alapokat, néhány konkrét szituációt meg tudunk nézni, hogy jobban megértsük a PUT és PATCH közötti különbséget az REST APIs-ben.
Példa forgatókönyvek: PUT vs PATCH a REST API-kban
Az elmélettől eltekintve, nézzünk meg konkrét példákat a PUT és PATCH közötti különbségről, beleértve az idempotens és nem-idempotens operációkat is.
Forgatókönyv 1: PUT kérés – Egy teljes erőforrás helyettesítése
Képzelj el egy API végpontot egy e-commerce rendszer termékeinek kezelésére. A termék összes részletét kell frissítened, beleértve annak nevét, árát és leírását. Ez egy tipikus eset a PUT vs PATCH összehasonlítására, ahol a PUT-ot a teljes termék erőforrás cseréjéhez használjuk.
Kezdeti Termék:
| GET /products/1001{"id": 1001,"name": "Laptop","price": 999.99,"description": "Egy erős laptop."} |
A termék árát és leírását szeretnéd frissíteni. Egy PUT kérést küldöl az egész erőforrással:
PUT Kérés:
| PUT /products/1001{"id": 1001,"name": "Laptop","price": 899.99,"description": "Egy kedvezményes erős laptop."} |
Ha ezt a PUT kérést egyszer vagy többször küldöd el, az eredmény mindig ugyanaz lesz. A termék részletei frissülni fognak az új árral és leírással, és minden alkalommal ugyanez az eredmény fog bekövetkezni. Ez garantálja a PUT idempotens természetét.
Eredmény (PUT kérés után):
| {"id": 1001,"name": "Laptop","price": 899.99,"description": "Egy kedvezményes, erőteljes laptop."} |
2. forgatókönyv: PATCH kérés - az erőforrás egy részének frissítése
Most nézzünk meg egy PATCH kérést, amely csak a termék adatainak egy részét, például a leírást frissíti. PATCH API példa: Ha a termék leírását szeretnéd megváltoztatni, de nem az árát, a PATCH a jobb választás. Ezt úgy valósíthatnád meg, hogy patch-eket hozol létre, amelyek csak a módosítandó mezőket tartalmazzák, például a leírást ebben a API REST PATCH példában.
Kezdeti Termék:
| GET /products/1001{"id": 1001,"name": "Laptop","price": 999.99,"description": "Egy erős laptop."} |
PATCH Kérés:
| PATCH /products/1001{"description": "Egy könnyű, erőteljes laptop."} |
Amikor ezt a PATCH kérést küldöd el, csak a leírás mező frissül. Ha ugyanezt a PATCH kérést többször küldöd el, a leírás az első frissítés után nem változik meg, így a kérés idempotens lesz.
Eredmény (PATCH kérés után):
| {"id": 1001,"name": "Laptop","price": 999.99,"description": "Egy könnyű, erőteljes laptop."} |
Ha ismét alkalmazod ugyanezt a PATCH-et, a termék leírása továbbra is ugyanaz marad, mint az első PATCH után. Az eredmény konzisztens, ami idempotensé teszi a PATCH-et ebben a forgatókönyvben.
Forgatókönyv 3: PATCH kérés – Nem idempotens művelet
Nézzünk meg egy nem-idempotens PATCH operációt. Tegyük fel, hogy van egy végpontod egy felhasználó tárca egyenlegéhez, és az egyenleget szeretnéd növelni. A PUT és PATCH közötti különbség erre az esetre jól szemléltethető: a PATCH egy értéket ad hozzá az egyenleghez minden alkalommal
Kezdeti Egyenleg:
| GET /users/1/wallet{"id": 1,"balance": 100.00} |
PATCH Kérés:
| PATCH /users/1/wallet{"increment": 50.00} |
Ez a PATCH kérés 50 dollárral növeli a pénztárca egyenlegét. Ha többször küldi el ezt a PATCH kérést, az egyenleg folyamatosan nő minden PATCH-nél, ami minden alkalommal más eredményt vezet. Ez nem idempotens, mivel ugyanazt a PATCH-et többször alkalmazva különböző kimenetel fog előfordulni.
Eredmény (az első PATCH kérés után):
| {"id": 1,"balance": 150.00} |
Eredmény (a második PATCH kérés után):
| {"id": 1,"balance": 200.00} |
Itt a PATCH nem idempotens, mert ugyanazokkal az adatokkal végzett ismételt kérések különböző eredményeket hoznak.
Összefoglalás: A PUT és a PATCH közötti főbb különbségek a REST API-kban
A PUT és PATCH közötti kulcsfontosságú különbség az REST API-ben az, hogy hogyan kezelik a frissítéseket. A PUT helyettesíti az egész erőforrást, így bármilyen hiányzó mező törlődik, ami adatvesztéshez vezethet. Ezért hoznak létre patch-eket a fejlesztők részleges frissítésekhez - a módosításon átesett mezők felülírásának elkerüléséhez és az adatintegritás megőrzéséhez.
Ez teszi a PATCH-et hatékonyabbá részleges frissítésekhez. A PATCH API például egy felhasználó e-mail-címének frissítésekor: csak az e-mail mezőt küldené el, míg egy PUT kérés a teljes felhasználói adatokat igényelné.
PUT esetén a teljes adatcsomagra szükség van. Ez azt jelenti, hogy minden mezőt el kell küldeni, és a hiányzó mezők törlődnek. A PATCH viszont csak az frissítendő mezőket küldi el, ami hatékonyabb, különösen nagy erőforrások esetén minimális változások mellett. A PATCH metódus a REST API-ben kisebb és céltudatosabb kéréseket tesz lehetővé, csökkentve az adatforgalmat.
A PUT és PATCH egyaránt idempotens. Ez azt jelenti, hogy ugyanaz a kérés többszöri megismétlése azonos eredményt hoz. A PUT azonban kiszámíthatóbb, mivel az egész erőforrást lecseréli. A PATCH, amikor csak meghatározott mezőket módosít, a szerver frissítéskezelésétől függően eltérő eredményekhez vezethet.
Például ha egy PATCH inkrementálja a számlálót, az ismételt kérések különböző kimenetelhez vezethetnek. A PATCH API műveletek azonban úgy is tervezhetők, hogy idempotensek legyenek.
Összefoglalva, a PUT és PATCH közötti különbség a REST API-ben a frissítések jellegéből adódik: a PATCH részleges változásokra, a PUT teljes erőforrás-csere céljára szolgál. Mindkettő idempotens, de a PATCH összetettebb lehet.
Végső gondolatok
A PUT és PATCH alapvető HTTP metódusok a REST API tervezésben, de eltérő célokat szolgálnak - ez a lényege a PUT és PATCH közötti különbségnek a REST API-ben. A API hatékonyságát, átláthatóságát és funkcionalitását jelentősen javíthatod, ha megérted a PUT és PATCH közötti különbséget a cikkben korábban ismertetett példákon keresztül. A helyes metódus (PATCH vagy REST frissítés) kiválasztásával a használati eset alapján a API hatékonyabbá, karbantarthatóbbá és felhasználóbarátabbá teheted. Mindig gondolj a frissítés jellegére - teljes vagy részleges-e - valamint a teljesítményre és az adatintegritásra gyakorolt hatásra, és válassza azt a módszert, amely legjobban megfelel az igényeidnek.
