A RESTful API-tervezésben a PUT és a PATCH két HTTP-módszer, amelyet a kiszolgálón lévő erőforrások frissítésére használnak, de a különbség a PUT és a PATCH között a REST API-kban abban rejlik, hogy hogyan hajtják végre a frissítéseket, és melyik forgatókönyv a legmegfelelőbb. Mindkét módszert a meglévő adatok módosítására tervezték, de a REST API-ban lévő PUT és PATCH különbségek megértése segíthet a fejlesztőknek a legmegfelelőbb választásban a végrehajtandó frissítés jellege alapján. Ebben a blogbejegyzésben megvizsgáljuk a PUT és a PATCH különbséget a REST API-ban, a PATCH és a frissítés REST vitájára összpontosítva, hogy mikor kell használni őket, és útmutatást adunk a megfelelő módszer kiválasztásához a különböző használati esetekhez.
Mi az a PUT a REST API-kban?
Ahhoz, hogy megértsük a különbséget a PUT és a PATCH között a REST API-kban, először is tudnunk kell, mi az a PUT. alapján 9.6 RFC 2616 szakasz, a REST API PUT metódusa azt kéri, hogy a zárt entitást a mellékelt Request-URI alatt tárolják.
Ha a Request-URI egy már létező erőforrásra hivatkozik, akkor a bezárt entitást az eredeti kiszolgálón található módosított változatának KELL tekinteni. Ha a Request-URI nem mutat egy meglévő erőforrásra, és ezt az URI-t a kérelmező felhasználói ügynök képes új erőforrásként meghatározni, akkor az eredeti kiszolgáló létrehozhatja az erőforrást ezzel az URI-val.
Más szavakkal, a PUT metódus egy teljes erőforrás frissítésére szolgál a kiszolgálón. Ez teszi a PUT-ot „teljesebb” frissítéssé, amelyet gyakran akkor használnak, ha az erőforrás teljes cseréjére van szükség.
Tehát a PUT a legjobb a következő felhasználási esetekben:
- Teljes erőforrás frissítése (pl. felhasználói profil frissítése minden új információval).
- Egy teljes elem vagy rekord cseréje.
- Amikor az erőforrás azonossága egyértelmű, és az adatait teljesen frissíteni kell.
Olyan rendszerekben, mint pl Elaszticsearch, idempotens műveletekre van szükség az adatok konzisztenciájának garantálásához. Például egy dokumentumnak az Elasticsearch programban a PUT használatával történő frissítése biztosítja, hogy ugyanaz a kérés nem kívánt mellékhatások nélkül megismétlődjön.
Mi az a PATCH a REST API-kban?
Most, hogy foglalkoztunk a PUT-val a REST API-kban, nézzük meg, mi a PATCH a REST API-kban, és hogyan működik, mielőtt összehasonlítanánk a PUT-t a PATCH-val a REST API-kban. pontjában meghatározottak szerint RFC 5789, a PATCH metódus a REST API-ban azt kéri, hogy a kérelem entitásban leírt változtatások készletét alkalmazzák a Request-URI által azonosított erőforrásra.
Ez igazodik a PUT vs PATCH REST API megkülönböztetéshez, ahol csak azokat az adatokat küldi el, amelyeket módosítani kell, és a kiszolgáló ezeket a módosításokat a meglévő erőforrásra alkalmazza anélkül, hogy a teljes erőforrást megváltoztatná. A fejlesztők gyakran készítenek javításokat ezeknek a növekményes változtatásoknak a megjelenítésére, minimális adatátvitelt és hatékony frissítéseket biztosítva.
Ezért a REST API PATCH metódusa jobban megfelel a következő felhasználási esetekben:
- Egy erőforrás mezőinek csak egy részhalmazának frissítése (például a felhasználó e-mail címének vagy telefonszámának megváltoztatása). A PATCH API példája magában foglalhatja az új e-mail elküldését, és a többi mezőt érintetlenül hagyja.
- A teljesítmény javítása az adatterhelés minimalizálásával.
- Ha egy erőforrást fokozatosan szeretne frissíteni, nem pedig teljesen lecserélni.
- Hozzon létre javításokat az egyes mezők módosításaihoz, például a felhasználó e-mail-címének módosításához, anélkül, hogy a nem kapcsolódó adatokat érintené.
Olyan platformokhoz, mint pl fej nélküli CMS amelyek gyakran bonyolult tartalomstruktúrákat kezelnek, a PATCH használatával kisebb frissítésekhez – például egyetlen mező módosításához – csökkenthető a szerver terhelése és javítható a teljesítmény.
Ha ezt a két módszert lefedi, tisztességes elképzeléssel kell rendelkeznie arról, hogy mi a PUT és a PATCH a REST API-kban. Mielőtt azonban rátérnénk a PUT és a PATCH közötti különbségre a REST API-kban, beszélnünk kell az Idempotenciáról ebben a két módszerben.
Idempotencia a PUT vs Patch-ben a REST API-kban
A REST API-kban az idempotencia egy művelet azon tulajdonságára utal, amely többszöri megismétlése ugyanazzal a bemenettel ugyanazt az eredményt eredményezi. Ez azt jelenti, hogy ugyanazon kérés többszöri végrehajtása ugyanolyan hatással kell, hogy legyen a szerverre, függetlenül attól, hogy hányszor kerül végrehajtásra. Ez fontos az API stabilitásának és kiszámíthatóságának biztosításához. De hogyan kapcsolódik ez a PUT és PATCH különbséghez a REST API-ban?
PUT módszer és idempotencia
A PUT metódus a REST API-ban mindig idempotens, mert úgy tervezték, hogy a teljes erőforrást lecserélje egy megadott URI-n a kérésben megadott adatokkal. Más szóval, ha többször hajt végre egy PUT-kérést ugyanazokkal az erőforrásadatokkal, az eredmény mindig ugyanaz lesz.
Miért a PUT Idempotens? Amikor PUT kérést ad le, lényegében azt mondja a kiszolgálónak: „Ez az a teljes és pontos állapot, amelyet szeretnék ehhez az erőforráshoz.” Akár egyszer, akár többször adja ki a PUT kérést, az eredményül kapott erőforrás mindig azonos lesz.
Vegyük például azt a forgatókönyvet, amikor frissíti a felhasználó e-mail címét. Ha többször is végrehajtja ugyanazt a PUT kérést, az eredmény nem változik, mivel az erőforrást minden alkalommal ugyanazok az adatok helyettesítik.
Példa:
| PUT /users/1{"felhasználónév": "john_doe","e-mail": "[email protected]"} |
Ha ezt a kérést többször is elküldi, az eredmény mindig ugyanaz lesz:
| {"felhasználónév": "john_doe","e-mail": "[email protected]"} |
Még ha a felhasználó adatai már ilyenek, a kérés újbóli elküldése nem változtat semmin. Az adatokat ugyanazokkal az adatokkal helyettesíti, így a kérés hatása ugyanaz marad, függetlenül attól, hogy hányszor ismétlődik. Ez teszi a PUT-ot idempotenssé.
PATCH módszer és idempotencia
A REST API PATCH metódusa viszont általában szintén idempotens, de nagyobb rugalmassággal. A javítások létrehozásakor ügyeljen arra, hogy a műveletek idempotensek legyenek (pl. érték beállítása), hogy elkerülje az ismételt kérések nem kívánt mellékhatásait. Az, hogy a PATCH idempotens-e, a művelettől és a módosítandó adatoktól függ.
Miért Idempotens a PATCH? PATCH kérések esetén az idempotencia azt jelenti, hogy ugyanazon javítás többszöri alkalmazása ugyanazt az eredményt fogja eredményezni. Ez mindaddig igaz, amíg maga a tapasz nem okoz további mellékhatásokat vagy változásokat, ha ismételten alkalmazzák. Ha továbbra is ugyanazt a javítást alkalmazza ugyanazokkal az adatokkal, az eredménynek az első alkalmazás után változatlannak kell lennie.
Például, ha csak egy felhasználó e-mail-címét frissíti, ugyanazon PATCH kérés ismételt elküldése nem változtatja meg az eredményt az első alkalom után, még akkor sem, ha a kérés többször történik. A felhasználó e-mail címe változatlan marad, és az erőforrás állapota nem változik.
PATCH API példa:
| PATCH /users/1{"e-mail": "[email protected]"} |
Ha az e-mail már a [email protected] cím volt, akkor ennek a PATCH-nak újbóli alkalmazása nem eredményez változást, így idempotens lesz.
A PATCH azonban bizonyos esetekben nem idempotens is lehet. Például, ha egy PATCH művelet módosít egy számlálót vagy elemeket ad hozzá egy listához (például növeli a számot vagy hozzáfűzi egy tömbhöz), ugyanazon PATCH ismételt alkalmazása eltérő eredményekhez vezethet. Ez sértené az idempotencia tulajdonságot.
Nem idempotens API REST PATCH Példa:
| PATCH /számláló/1{"növekmény": 1} |
Ha ezt a PATCH-et többször alkalmazza, a számláló folyamatosan növekszik, ami minden alkalommal más értékeket eredményez. Ez nem idempotens, mert az eredmény minden alkalmazással változik.
Most, hogy ismeri a lényeget, megtekinthetünk néhány példa forgatókönyvet, hogy jobban megértsük a különbséget a PUT és a PATCH között a REST API-kban.
Példaforgatókönyvek: PUT vs PATCH REST API-kban
Az elmélettől eltekintve, nézzük meg a PUT és a PATCH közötti különbséget példákkal, beleértve az idempotens és nem idempotens műveleteket is.
1. forgatókönyv: PUT-kérés – Egy teljes erőforrás cseréje
Képzeljen el egy API-végpontot a termékek kezeléséhez egy e-kereskedelmi rendszerben. Frissítenie kell a termék összes részletét, beleértve a nevét, árát és leírását. Ez egy tipikus példa a PUT vs PATCH HTTP metódusra, ahol a PUT a teljes termékerőforrás lecserélésére szolgál.
Kezdeti termék:
| GET /products/1001{"id": 1001,"name": "Laptop","price": 999.99,"description": "Egy nagy teljesítményű laptop."} |
Frissíteni szeretné a termék árát és leírását. PUT kérést küld a teljes erőforrással:
PUT kérés:
| PUT /products/1001{"id": 1001,"name": "Laptop","price": 899.99,"description": "Akciós nagy teljesítményű laptop."} |
Ha ezt a PUT kérést egyszer vagy többször adja meg, az eredmény mindig ugyanaz lesz. A termék adatai frissülnek, hogy tükrözzék az új árat és leírást, és minden alkalommal ugyanaz lesz az eredmény. Ez biztosítja a PUT idempotens természetét.
Eredmény (PUT-kérés után):
| {"id": 1001,"name": "Laptop","price": 899.99,"description": "Akciós nagy teljesítményű laptop."} |
2. forgatókönyv: PATCH kérés – az erőforrás egy részének frissítése
Most pedig vegyünk egy PATCH kérést a termék részleteinek, például a leírásnak csak egy részének frissítésére. PATCH API példa: Ha módosítani szeretné a termék leírását, de nem az árát, a PATCH a jobb választás. Ennek megvalósításához olyan javításokat kell létrehoznia, amelyek csak a módosítást igénylő mezőket tartalmazzák, például az API REST PATCH példájában található leírást.
Kezdeti termék:
| GET /products/1001{"id": 1001,"name": "Laptop","price": 999.99,"description": "Egy nagy teljesítményű laptop."} |
PATCH kérés:
| PATCH /products/1001{"description": "Egy könnyű, erős laptop."} |
Amikor elküldi ezt a PATCH kérést, csak a leírás mező frissül. Ha többször is elküldi ugyanazt a PATCH kérést, a leírás változatlan marad az első frissítés után, így a kérés idempotens.
Eredmény (PATCH kérés után):
| {"id": 1001,"name": "Laptop","price": 999.99,"description": "Egy könnyű, erős laptop."} |
Ha újra felhelyezi ugyanazt a PATCH-et, a termékleírás továbbra is ugyanaz marad, mint az első PATCH után. Az eredmény konzisztens, ami a PATCH-ot idempotenssé teszi ebben a forgatókönyvben.
3. forgatókönyv: PATCH kérés – nem idempotens működés
Nézzünk egy nem idempotens PATCH műveletet. Tegyük fel, hogy van egy végpont a felhasználó pénztárcaegyenlegének, és növelni szeretné az egyenleget. A PUT és a PATCH közötti különbség példája itt szemléltethető: A PATCH minden alkalommal hozzáad egy értéket az egyenleghez
Kezdeti pénztárca:
| GET /users/1/wallet{"azonosító": 1,"egyenleg": 100,00} |
PATCH kérés:
| PATCH /felhasználók/1/pénztárca{"növekmény": 50,00} |
Ez a PATCH kérés 50 dollárral növeli a pénztárca egyenlegét. Ha ezt a PATCH kérést többször elküldi, az egyenleg minden PATCH-mal folyamatosan növekszik, ami minden alkalommal más eredményhez vezet. Ez nem idempotens, mert ugyanazon PATCH ismételt alkalmazása eltérő eredményt eredményez.
Eredmény (az első PATCH kérés után):
| {"azonosító": 1,"egyenleg": 150,00} |
Eredmény (a második PATCH-kérés után):
| {"azonosító": 1,"egyenleg": 200,00} |
Itt a PATCH nem idempotens, mert az ugyanazokkal az adatokkal ismételt kérések eltérő eredményeket adnak.
Összefoglaló: Főbb különbségek a PUT és a PATCH között a REST API-kban
A legfontosabb különbség a PUT és a PATCH között a REST API-ban az, hogy hogyan kezelik a frissítéseket. A PUT lecseréli a teljes erőforrást, így a hiányzó mezők törlődnek, ami adatvesztéshez vezethet. Ez az oka annak, hogy a fejlesztők javításokat hoznak létre a részleges frissítésekhez – a változatlan mezők felülírásának elkerülése és az adatok integritásának megőrzése érdekében.
Ez hatékonyabbá teszi a PATCH-ot a részleges frissítésekhez. A PATCH API példája az, hogy ha csak egy felhasználó e-mail-címét szeretné frissíteni, a javítások létrehozása csak az e-mail mezőt küldi el, ellentétben a PUT kéréssel, amelyhez a teljes felhasználói adatra lenne szükség.
A PUT esetén a teljes adatterhelésre van szükség. Ez azt jelenti, hogy minden mezőt el kell küldeni, és a hiányzó mezők törlődnek. A PATCH azonban csak a frissítésre szoruló mezőket küldi el, így hatékonyabbá válik, különösen nagy erőforrások esetén, minimális változtatásokkal. A PATCH módszer a REST API-ban célzottabb és kisebb kéréseket tesz lehetővé, csökkentve az adatátvitelt.
A PUT és a PATCH is idempotens. Ez azt jelenti, hogy ugyanazon kérés megismétlése ugyanazt az eredményt fogja eredményezni. A PUT azonban kiszámíthatóbb, mivel a teljes erőforrást helyettesíti. A PATCH csak meghatározott mezők módosítására használva eltérő eredményekhez vezethet attól függően, hogy a kiszolgáló hogyan kezeli a frissítéseket.
Például, ha a PATCH növeli a számlálót, az ismételt kérések eltérő eredményekhez vezethetnek. Mindazonáltal a PATCH API-műveleteket idempotensre is meg lehet tervezni.
Összefoglalva, a PUT és a PATCH különbség a REST API-ban a frissítések természetére vezethető vissza: a PATCH a részleges változtatásokat, míg a PUT a teljes erőforráscserét jelenti. Mindkettő idempotens, de a PATCH bonyolultabb is lehet.
Végső gondolatok
Mind a PUT, mind a PATCH alapvető HTTP metódusok a REST API tervezésében, de különböző célokat szolgálnak, ami a REST API PUT és PATCH különbségének lényege. Jelentősen javíthatja az API hatékonyságát, egyértelműségét és funkcionalitását, ha megérti a PUT és a PATCH közötti különbséget a cikkben korábban tárgyalt példákkal. Ha a használati esete alapján a megfelelő módszert választja (PATCH vs frissítés REST), hatékonyabbá, karbantarthatóbbá és felhasználóbarátabbá teheti API-ját. Mindig vegye figyelembe a frissítés jellegét – akár teljes, akár részleges –, valamint a teljesítményre és az adatok integritására gyakorolt hatást, és válassza ki az igényeinek leginkább megfelelő módszert.
