V RESTful API designu jsou PUT a PATCH dvě HTTP metody používané k aktualizaci zdrojů na serveru, ale rozdíl mezi PUT a PATCH v REST APIs spočívá v tom, jak provádějí aktualizace a v jakých scénářích je každá metoda nejvhodnější. Obě metody jsou určeny k úpravě existujících dat, ale pochopení rozdílu mezi PUT a PATCH v REST API může vývojářům pomoci zvolit nejlepší metodu na základě povahy aktualizace, kterou potřebují provést. V tomto příspěvku na blogu prozkoumáme rozdíl mezi PUT a PATCH v REST API, zaměřte se na debatu PATCH vs aktualizace REST, kdy použít každou metodu, a poskytneme pokyny pro výběr správné metody pro různé případy použití.
Co je PUT v REST APIs?
Abychom pochopili rozdíl mezi PUT a PATCH v REST APIs, musíme nejdřív vědět, co je PUT. Podle Oddíl 9.6 RFC 2616, metoda PUT v REST API požaduje, aby byla uzavřená entita uložena pod poskytnutým Request-URI.
Pokud se Request-URI odkazuje na již existující zdroj, měla by být uzavřená entita považována za upravenou verzi zdroje na původním serveru. Pokud se Request-URI neodkazuje na existující zdroj a tento URI může být uživatelským agentem požadujícím definován jako nový zdroj, může původní server vytvořit zdroj s tímto URI.
Jinými slovy, metoda PUT se používá k aktualizaci celého zdroje na serveru. To dělá PUT úplnější aktualizací, často používanou, když je nezbytné úplné nahrazení zdroje.
PUT je tedy vhodný pro tyto případy použití:
- Aktualizace kompletního zdroje (například aktualizace profilu uživatele se všemi novými informacemi).
- Nahrazení celé položky nebo záznamu.
- Pokud je jasně určena identita zdroje a jeho data je třeba zcela osvěžit.
V systémech jako Elasticsearch, jsou idempotentní operace nezbytné k zajištění konzistence dat. Například aktualizace dokumentu v Elasticsearch pomocí PUT zajišťuje, že stejný požadavek lze opakovat bez nežádoucích vedlejších účinků.
Co je PATCH v REST APIs?
Teď, když jsme se zabývali PUT v REST APIs, podívejme se, co je PATCH v REST APIs a jak funguje, dříve než porovnáme PUT a PATCH v REST APIs. Jak je definováno v RFC 5789, metoda PATCH v REST API požaduje, aby byla sada změn popsaných v entitě požadavku aplikována na zdroj identifikovaný Request-URI.
To se shoduje s rozlišením PUT a PATCH REST API, kde posílate pouze data, která je třeba upravit, a server tyto změny aplikuje na existující zdroj bez změny celého zdroje. Vývojáři často vytvářejí patche, aby reprezentovaly tyto postupné změny, což zajišťuje minimální přenos dat a efektivní aktualizace.
Proto je metoda PATCH v REST API vhodnější pro následující případy použití:
- Aktualizace pouze podmnožiny polí v prostředku (např. změna e-mailové adresy nebo telefonního čísla uživatele). Příklad PATCH API by mohl zahrnovat odeslání pouze nové e-mailové adresy, přičemž ostatní pole zůstávají nezměněna.
- Zvýšení výkonu minimalizací objemu přenášených dat.
- Pokud chcete aktualizovat prostředek postupně místo jeho úplné výměny.
- Vytvářejte patches, které zapouzdřují konkrétní změny polí, jako je úprava e-mailu uživatele, bez ovlivnění nepříbuzných dat.
Pro platformy jako bezhlavi CMS které často pracují se složitými strukturami obsahu, může použití PATCH pro menší aktualizace, jako je úprava jednoho pole, snížit zátěž serveru a zlepšit výkon.
Pokud jste si osvojili tyto dvě metody, měli byste mít solidní představu o tom, co jsou PUT a PATCH v REST APIs. Než se ale pustíme do rozdílu mezi PUT a PATCH v REST APIs, musíme si povědět něco o idempotenci těchto dvou metod.
Idempotence v PUT vs Patch v REST APIs
V REST APIs se idempotence vztahuje na vlastnost operace, která při opakování několikrát se stejnými vstupy vede na stejný výsledek. To znamená, že opakované odeslání stejné žádosti by mělo mít na server stejný vliv, nezávisle na tom, kolikrát je provedena. To je důležité pro zajištění stability a předvídatelnosti v API. Ale jak se to vztahuje k rozdílu mezi PUT a PATCH v REST API?
Metoda PUT a idempotence
Metoda PUT v REST API je vždy idempotentní, protože je navržena tak, aby nahradila celý prostředek na zadaném URI daty obsaženými v žádosti. Jinými slovy, pokud provedete PUT žádost vícekrát se stejnými daty prostředku, výsledek bude vždy stejný.
Proč je PUT idempotentní? Když odešlete PUT žádost, v podstatě serveru říkáte: "Toto je úplný a přesný stav, který chci pro tento prostředek." Ať již odešlete PUT žádost jednou nebo vícekrát, výsledný prostředek bude vždy stejný.
Uvažujme například situaci, kdy aktualizujete e-mailovou adresu uživatele. Pokud odešlete stejnou PUT žádost vícekrát, výsledek se nezmění, protože prostředek se nahrazuje stejnými daty pokaždé.
Příklad:
| PUT /users/1{"username": "john_doe","email": "[email protected]"} |
Pokud tuto žádost odešlete vícekrát, výsledek bude vždy stejný:
| {"username": "john_doe","email": "[email protected]"} |
I pokud jsou data uživatele již v tomto stavu, opětovné odeslání žádosti nic nezměni. Nahradí data stejnými daty, takže efekt žádosti zůstává stejný bez ohledu na to, kolikrát se zopakuje. To je to, co dělá PUT idempotentní.
Metoda PATCH a idempotence
Metoda PATCH v REST API je na druhou stranu obecně také idempotentní, ale s větší flexibilitou. Když vytváříte patches, zajistěte, aby byly operace idempotentní (např. nastavení hodnoty), abyste zabránili nežádoucím vedlejším efektům z opakovaných žádostí. To, zda je PATCH idempotentní, závisí na operaci a datech, která jsou upravována.
Proč je PATCH idempotentní? Pro PATCH žádosti idempotence znamená, že aplikace stejného patche vícekrát bude mít stejný výsledek. To platí, pokud patch sám o sobě nezpůsobí dodatečné vedlejší efekty nebo změny při opakované aplikaci. Pokud budete opakovaně aplikovat stejný patch se stejnými daty, výsledek by měl zůstat nezměněn po první aplikaci.
Pokud například aktualizujete pouze e-mailovou adresu uživatele, opakované odeslání stejné PATCH žádosti nezmění výsledek po prvním odeslání, i když je žádost provedena několikrát. E-mail uživatele zůstane stejný a stav prostředku se nezmění.
Příklad PATCH API:
| PATCH /users/1{"email": "[email protected]"} |
Pokud byl e-mail již [email protected], pak opětovná aplikace tohoto PATCHu nezmění nic, čímž se stane idempotentní.
PATCH však může být v některých případech také non-idempotentní. Pokud například operace PATCH upravuje čítač nebo přidává položky do seznamu (jako je zvýšení čísla nebo přidání do pole), opakované aplikace stejného PATCHu by mohly vést k různým výsledkům. To by porušilo vlastnost idempotence.
Příklad non-idempotentního API REST PATCHu:
| PATCH /counter/1{"increment": 1} |
Pokud tento PATCH opakovaně aplikujete, čítač se bude dále zvyšovat a pokaždé vrátí jinou hodnotu. Toto není idempotentní, protože se výsledek mění s každou aplikací.
Nyní, když znáte základy, můžeme se podívat na konkrétní scénáře a lépe pochopit rozdíl mezi PUT a PATCH v REST APIs.
Příklady scénářů: PUT vs PATCH v REST APIs
Pojďme se zbavit teorie a podívejme se na konkrétní rozdíly mezi PUT a PATCH s příklady, včetně idempotentních i neidentompotentních operací.
Scénář 1: PUT požadavek – Nahrazení celého prostředku
Představte si API endpoint pro správu produktů v e-commerce systému. Musíte aktualizovat všechny detaily produktu včetně názvu, ceny a popisu. Toto je typický příklad HTTP metody PUT vs PATCH, kde se PUT používá k nahrazení celého prostředku produktu.
Počáteční produkt:
| GET /products/1001{"id": 1001,"name": "Laptop","price": 999.99,"description": "A powerful laptop."} |
Chcete aktualizovat cenu a popis produktu. Odešlete PUT požadavek s celým prostředkem:
PUT Požadavek:
| PUT /products/1001{"id": 1001,"name": "Laptop","price": 899.99,"description": "A discounted powerful laptop."} |
Pokud odešlete tento PUT požadavek jednou nebo vícekrát, výsledek bude vždy stejný. Detaily produktu se aktualizují na novou cenu a popis a pokaždé se dosáhne stejného výsledku. Tím se zajistí idempotentní povaha PUT.
Výsledek (Po PUT požadavku):
| {"id": 1001,"name": "Laptop","price": 899.99,"description": "A discounted powerful laptop."} |
Scénář 2: PATCH požadavek – Aktualizace části prostředku
Nyní zvažte PATCH požadavek na aktualizaci pouze části detailů produktu, například popisu. PATCH API příklad: Pokud chcete změnit popis produktu, ale ne jeho cenu, PATCH je lepší volbou. Chcete-li to implementovat, vytvořte patche obsahující pouze pole vyžadující úpravu, jako je popis v tomto API REST PATCH příkladu.
Počáteční produkt:
| GET /products/1001{"id": 1001,"name": "Laptop","price": 999.99,"description": "A powerful laptop."} |
PATCH Požadavek:
| PATCH /products/1001{"description": "A lightweight, powerful laptop."} |
Když odešlete tento PATCH požadavek, aktualizuje se pouze pole popisu. Pokud odešlete stejný PATCH požadavek vícekrát, popis zůstane po první aktualizaci nezměněn, čímž je požadavek idempotentní.
Výsledek (Po PATCH požadavku):
| {"id": 1001,"name": "Laptop","price": 999.99,"description": "A lightweight, powerful laptop."} |
Pokud aplikujete stejný PATCH znovu, popis produktu zůstane stejný jako po prvním PATCH. Výsledek je konzistentní, což dělá PATCH v tomto scénáři idempotentním.
Scénář 3: PATCH požadavek – Neidentompotentní operace
Podívejme se na neidentompotentní PATCH operaci. Předpokládejme, že existuje endpoint pro zůstatek peněženky uživatele a chcete zůstatek zvýšit. Příklad rozdílu mezi PUT a PATCH lze ilustrovat zde: PATCH přidá hodnotu k zůstatku pokaždé
Počáteční Peněženka:
| GET /users/1/wallet{"id": 1,"balance": 100.00} |
PATCH Požadavek:
| PATCH /users/1/wallet{"increment": 50.00} |
Tento PATCH požadavek zvýší zůstatek peněženky o 50 dolarů. Pokud odešlete tento PATCH požadavek vícekrát, zůstatek se bude s každým PATCH zvyšovat, což vede k různému výsledku pokaždé. Toto je neidentompotentní, protože opakovaná aplikace stejného PATCH vede k odlišnému výsledku.
Výsledek (Po prvním PATCH požadavku):
| {"id": 1,"balance": 150.00} |
Výsledek (Po druhém PATCH požadavku):
| {"id": 1,"balance": 200.00} |
Zde PATCH není idempotentní, protože opakované požadavky se stejnými daty produkují různé výsledky.
Shrnutí: Klíčové rozdíly mezi PUT a PATCH v REST APIs
Klíčový rozdíl mezi PUT a PATCH v REST API spočívá v tom, jak zpracovávají aktualizace. PUT nahrazuje celý zdroj, takže všechna chybějící pole se vymažou, což může vést ke ztrátě dat. Proto vývojáři vytvářejí opravy pro částečné aktualizace - aby se vyhnuli přepsání nezměněných polí a zachovali integritu dat.
Díky tomu je PATCH efektivnější pro částečné aktualizace. Příkladem PATCH API je, když chcete aktualizovat pouze email uživatele - oprava by poslala jen pole email, na rozdíl od PUT požadavku, který by vyžadoval veškeré údaje o uživateli.
U PUT je vyžadován úplný datový obsah. To znamená, že musí být odeslano každé pole, a všechna chybějící pole budou smazána. PATCH však posílá pouze pole, která je třeba aktualizovat, takže je efektivnější, zvláště pro velké zdroje s minimálními změnami. Metoda PATCH v REST API umožňuje více zaměřené a menší požadavky, což snižuje přenos dat.
Jak PUT tak PATCH jsou idempotentní. To znamená, že opakování stejného požadavku bude mít za následek stejný výsledek. Nicméně PUT je předvídatelnější, protože nahrazuje celý zdroj. PATCH, když se používá pouze k úpravě určených polí, může vést k různým výsledkům v závislosti na tom, jak server zpracovává aktualizace.
Například pokud PATCH zvyšuje čítač, opakované požadavky by mohly vést k různým výsledkům. Přesto operace PATCH API lze navrhnout tak, aby byly také idempotentní.
Závěrem lze říci, že rozdíl mezi PUT a PATCH v REST API spočívá v povaze aktualizací: PATCH slouží k částečným změnám, zatímco PUT k úplné náhradě zdroje. Obě jsou idempotentní, ale PATCH může být složitější.
Závěrečné myšlenky
Jak PUT tak PATCH jsou základními metodami HTTP v návrhu REST API, ale slouží různým účelům - to je podstata rozdílu mezi PUT a PATCH v REST API. Pochopením rozdílu mezi PUT a PATCH na příkladech, které jsme zde probrali, můžete výrazně zlepšit efektivitu, jasnost a funkcionalitu vašeho API. Výběrem správné metody (PATCH vs aktualizace REST) na základě vašeho případu použití můžete udělat váš API efektivnějším, lépe udržovatelným a uživatelsky přívětivějším. Vždy zvažte povahu aktualizace - zda je úplná nebo částečná - a její dopad na výkon a integritu dat, a zvolte metodu, která nejlépe odpovídá vašim potřebám.
