V návrhu RESTful API jsou PUT a PATCH dvě metody HTTP používané k aktualizaci zdrojů na serveru, ale rozdíl mezi PUT a PATCH v REST API je v tom, jak provádějí aktualizace a ve scénářích, ve kterých je každá nejvhodnější. Obě metody jsou navrženy tak, aby upravovaly existující data, ale pochopení rozdílu PUT a PATCH v REST API může vývojářům pomoci učinit nejlepší volbu 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 a zaměříme se na debatu PATCH vs. aktualizace REST, kdy je použít, a poskytneme pokyny pro výběr správné metody pro různé případy použití.
Co je PUT v REST API?
Abychom pochopili rozdíl mezi PUT a PATCH v REST API, musíme nejprve vědět, co je PUT. Na základě Oddíl 9.6 RFC 2616, metoda PUT v REST API vyžaduje, aby byla uzavřená entita uložena pod dodaným identifikátorem URI požadavku.
Pokud identifikátor URI požadavku odkazuje na již existující zdroj, uzavřená entita BY MĚLA být považována za upravenou verzi té, která se nachází na původním serveru. Pokud identifikátor URI požadavku neukazuje na existující zdroj a tento URI může být definován jako nový zdroj žádajícím uživatelským agentem, může zdrojový server vytvořit zdroj s tímto URI.
Jinými slovy, metoda PUT se používá k aktualizaci celého prostředku na serveru. Díky tomu je PUT „kompletnější“ aktualizací, která se často používá, když je nutná úplná výměna zdroje.
PUT je tedy nejlepší pro následující případy použití:
- Aktualizace kompletního zdroje (např. aktualizace uživatelského profilu se všemi novými informacemi).
- Nahrazení celé položky nebo záznamu.
- Když je identita zdroje jasná a jeho data je třeba plně aktualizovat.
V systémech jako ElasticsearchPro zajištění konzistence dat jsou nezbytné idempotentní operace. Například aktualizace dokumentu v Elasticsearch pomocí PUT zajišťuje, že stejný požadavek lze opakovat bez nezamýšlených vedlejších účinků.
Co je PATCH v REST API?
Nyní, když jsme probrali PUT v REST API, podívejme se, co je PATCH v REST API a jak funguje, než porovnáme PUT vs PATCH v REST API. Jak je definováno v RFC 5789metoda PATCH v REST API požaduje, aby sada změn popsaných v entitě požadavku byla aplikována na zdroj identifikovaný pomocí Request-URI.
To je v souladu s rozlišením PUT vs PATCH REST API, kde odesíláte pouze data, která je třeba upravit, a server aplikuje tyto změny na existující prostředek, aniž by změnil celý prostředek. Vývojáři často vytvářejí záplaty, které reprezentují tyto postupné změny a zajišťují 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í ve zdroji (např. změna e-mailové adresy nebo telefonního čísla uživatele). Příklad PATCH API může zahrnovat odeslání pouze nového e-mailu, přičemž ostatní pole zůstanou nedotčená.
- Zlepšení výkonu minimalizací datové zátěže.
- Když chcete zdroj aktualizovat postupně, místo abyste jej úplně nahradili.
- Vytvářejte záplaty pro zapouzdření konkrétních změn polí, jako je úprava e-mailu uživatele, aniž by to ovlivnilo nesouvisející data.
Pro platformy jako bezhlavý CMS které často zvládají složité struktury obsahu, může použití PATCH pro menší aktualizace – jako je úprava jednoho pole – snížit zatížení serveru a zlepšit výkon.
S těmito dvěma metodami byste měli mít slušnou představu o tom, co jsou PUT a PATCH v REST API. Než se však dostaneme k rozdílu mezi PUT a PATCH v REST API, musíme si promluvit o Idempotenci v těchto dvou metodách.
Idempotence In PUT Vs Patch v REST API
V REST API se idempotence týká vlastnosti operace, která, když se několikrát opakuje se stejnými vstupy, vede ke stejnému výsledku. To znamená, že vícenásobné zadání stejného požadavku by mělo mít na server stejný účinek, bez ohledu na to, kolikrát byl proveden. To je důležité pro zajištění stability a předvídatelnosti v API. Ale jak je to relevantní pro rozdíl 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ý zdroj na zadaném URI daty poskytnutými v požadavku. Jinými slovy, pokud provedete požadavek PUT vícekrát se stejnými daty zdrojů, výsledek bude vždy stejný.
Proč je PUT Idempotent? Když zadáte požadavek PUT, v podstatě říkáte serveru: "Toto je úplný a přesný stav, který pro tento zdroj chci." Ať už zadáte požadavek PUT jednou nebo mnohokrát, výsledný zdroj bude vždy stejný.
Zvažte například scénář, kdy aktualizujete e-mailovou adresu uživatele. Pokud stejný požadavek PUT zadáte vícekrát, výsledek se nezmění, protože zdroj je pokaždé nahrazen stejnými daty.
Příklad:
| PUT /users/1{“uživatelské_jméno“: “jan_novak”,”email”: “[email protected]”} |
Pokud tento požadavek odešlete vícekrát, výsledek bude vždy stejný:
| {“username”: “john_doe”,”email”: “[email protected]”} |
I když jsou data uživatele již taková, opětovným odesláním požadavku se nic nemění. Nahrazuje data stejnými daty, takže efekt požadavku zůstává stejný bez ohledu na to, kolikrát se opakuje. To je to, co dělá PUT idempotentním.
PATCH metoda a idempotence
Metoda PATCH v REST API je na druhé straně obecně idempotentní, ale s větší flexibilitou. Když vytváříte záplaty, ujistěte se, že operace jsou idempotentní (např. nastavení hodnoty), abyste předešli nechtěným vedlejším účinkům opakovaných požadavků. Zda je PATCH idempotentní, závisí na operaci a modifikovaných datech.
Proč je PATCH Idempotent? U požadavků PATCH idempotence znamená, že použití stejné opravy vícekrát bude mít stejný výsledek. To platí, pokud náplast sama o sobě nezpůsobuje další vedlejší účinky nebo změny při opakované aplikaci. Pokud stále aplikujete stejnou náplast se stejnými údaji, výsledek by měl být po první aplikaci nezměněn.
Pokud například pouze aktualizujete e-mail uživatele, opakované odesílání stejného požadavku PATCH nezmění výsledek po prvním pokusu, i když byl požadavek podán několikrát. E-mail uživatele zůstane stejný a stav zdroje se nezmění.
Příklad PATCH API:
| OPRAVA /users/1{“e-mail“: “[email protected]”} |
Pokud byl e-mail již [email protected], pak opětovné použití této opravy nebude mít za následek žádnou změnu, takže bude idempotentní.
PATCH však může být v některých případech také neidempotentní. Pokud například operace PATCH upraví čítač nebo přidá položky do seznamu (jako je zvýšení čísla nebo připojení k poli), opakované aplikace stejného PATCH by mohly vést k různým výsledkům. To by porušilo vlastnost idempotence.
Neidempotentní API REST PATCH Příklad:
| PATCH /counter/1{"přírůstek": 1} |
Pokud tento PATCH aplikujete opakovaně, počítadlo se bude neustále zvyšovat, což má za následek pokaždé jiné hodnoty. To není idempotentní, protože výsledek se mění s každou aplikací.
Nyní, když znáte to podstatné, můžeme se podívat na několik příkladů scénářů, abychom lépe porozuměli rozdílu mezi PUT a PATCH v REST API.
Příklad scénáře: PUT vs PATCH v REST API
Pomineme-li teorii, podívejme se na rozdíl mezi PUT a PATCH s příklady, včetně idempotentních i neidempotentních operací.
Scénář 1: Požadavek PUT – Výměna celého zdroje
Představte si koncový bod API pro správu produktů v systému elektronického obchodování. Musíte aktualizovat všechny podrobnosti o produktu, včetně jeho názvu, ceny a popisu. Toto je typický příklad HTTP metody PUT vs PATCH, kde se PUT používá k nahrazení celého zdroje produktu.
Počáteční produkt:
| GET /products/1001{“id”: 1001,”name”: “Laptop”,”price”: 999,99,”description”: “Výkonný notebook.”} |
Chcete aktualizovat cenu a popis produktu. Odešlete požadavek PUT s celým zdrojem:
Požadavek PUT:
| PUT /products/1001{“id”: 1001,”name”: “Laptop”,”price”: 899,99,”description”: “Zlevněný výkonný notebook.”} |
Pokud tento požadavek PUT provedete jednou nebo vícekrát, výsledek bude vždy stejný. Podrobnosti o produktu budou aktualizovány, aby odrážely novou cenu a popis, a pokaždé dojde ke stejnému výsledku. To zajišťuje idempotentní povahu PUT.
Výsledek (po požadavku PUT):
| {“id”: 1001,”name”: “Laptop”,”price”: 899,99,”description”: “Zlevněný výkonný notebook.”} |
Scénář 2: Požadavek PATCH – Aktualizace části zdroje
Nyní se podívejme na požadavek PATCH pro aktualizaci pouze části podrobností o produktu, jako je popis. Příklad PATCH API: Pokud chcete změnit popis produktu, ale ne jeho cenu, PATCH je lepší volba. Chcete-li to implementovat, vytvořili byste opravy obsahující pouze pole vyžadující úpravu, jako je popis v tomto příkladu REST PATCH rozhraní API.
Počáteční produkt:
| GET /products/1001{“id”: 1001,”name”: “Laptop”,”price”: 999,99,”description”: “Výkonný notebook.”} |
Žádost o PATCH:
| PATCH /products/1001{"description": "Lehký a výkonný notebook."} |
Když odešlete tento požadavek PATCH, aktualizuje se pouze pole popisu. Pokud stejný požadavek PATCH odešlete vícekrát, popis zůstane po první aktualizaci nezměněn, takže požadavek bude idempotentní.
Výsledek (po požadavku PATCH):
| {“id”: 1001,”name”: “Laptop”,”price”: 999,99,”description”: “Lehký a výkonný notebook.”} |
Pokud znovu použijete stejný PATCH, popis produktu bude stále stejný jako po prvním PATCHU. Výsledek je konzistentní, díky čemuž je PATCH v tomto scénáři idempotentní.
Scénář 3: Požadavek PATCH – neidempotentní operace
Podívejme se na neidempotentní operaci PATCH. Předpokládejme, že existuje koncový bod pro zůstatek v peněžence uživatele a chcete zůstatek navýš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,”zůstatek”: 100,00} |
Žádost o PATCH:
| PATCH /users/1/wallet{“přírůstek“: 50,00} |
Tento požadavek PATCH zvýší zůstatek v peněžence o 50 $. Pokud tento požadavek na PATCH odešlete vícekrát, zůstatek se bude s každým PATCHem zvyšovat, což pokaždé povede k jinému výsledku. To není idempotentní, protože opakované použití stejného PATCH způsobí jiný výsledek.
Výsledek (po prvním požadavku PATCH):
| {"id": 1,"zůstatek": 150,00} |
Výsledek (po druhém požadavku PATCH):
| {"id": 1,"zůstatek": 200,00} |
Zde PATCH není idempotentní, protože opakované požadavky se stejnými daty přinášejí různé výsledky.
Shrnutí: Klíčové rozdíly mezi PUT a PATCH v REST API
Klíčovým rozdílem mezi PUT a PATCH v REST API je způsob, jakým zpracovávají aktualizace. PUT nahradí celý zdroj, takže všechna chybějící pole jsou vymazána, což může vést ke ztrátě dat. To je důvod, proč vývojáři vytvářejí záplaty 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 dílčí aktualizace. Příkladem PATCH API je, že pokud chcete aktualizovat pouze e-mail uživatele, vytvoření oprav by odeslalo pouze pole e-mailu, na rozdíl od požadavku PUT, který by vyžadoval celá uživatelská data.
S PUT je vyžadována plná datová zátěž. To znamená, že každé pole musí být odesláno a všechna chybějící pole budou vymazána. PATCH však odesílá pouze pole, která je třeba aktualizovat, což je efektivnější, zejména u velkých zdrojů s minimálními změnami. Metoda PATCH v REST API umožňuje cílenější a menší požadavky, což snižuje přenos dat.
PUT i PATCH jsou idempotentní. To znamená, že opakování stejného požadavku povede ke stejnému výsledku. PUT je však předvídatelnější, protože nahrazuje celý zdroj. PATCH, pokud se používá k úpravě pouze zadaných polí, může vést k různým výsledkům v závislosti na tom, jak server zpracovává aktualizace.
Pokud například PATCH zvýší čítač, opakované požadavky mohou vést k různým výsledkům. Nicméně operace PATCH API mohou být navrženy tak, aby byly idempotentní.
Závěrem lze říci, že rozdíl mezi PUT a PATCH v REST API se scvrkává na povahu aktualizací: PATCH je pro dílčí změny, zatímco PUT je pro úplnou náhradu zdrojů. Oba jsou idempotentní, ale PATCH může být složitější.
Závěrečné myšlenky
PUT i PATCH jsou základní metody HTTP v návrhu REST API, ale slouží různým účelům, což je podstatou rozdílu PUT a PATCH v REST API. Efektivitu, srozumitelnost a funkčnost svého API můžete výrazně zlepšit tím, že pochopíte rozdíl mezi PUT a PATCH pomocí příkladů, které jsme probrali dříve v tomto článku Výběrem správné metody (PATCH vs. aktualizace REST) na základě vašeho případu použití můžete své API učinit efektivnější, udržovatelnější a uživatelsky přívětivější. Vždy zvažte povahu aktualizace – zda je úplná nebo částečná – spolu s dopadem na výkon a integritu dat a vyberte metodu, která nejlépe odpovídá vašim potřebám.
