HTTP PUT vs HTTP PATCH v REST API

1. Prehľad

V tomto rýchlom článku sa zameriavame na rozdiely medzi slovesami HTTP PUT a PATCH a na sémantiku týchto dvoch operácií.

Spring použijeme na implementáciu dvoch koncových bodov REST, ktoré podporujú tieto dva typy operácií, a na lepšie pochopenie rozdielov a správny spôsob ich použitia.

2. Kedy použiť Put a When Patch?

Začnime jednoduchým a trochu jednoduchým výrokom.

Ak klient potrebuje úplne nahradiť existujúci zdroj, môže použiť program PUT. Keď robia čiastočnú aktualizáciu, môžu použiť HTTP PATCH.

Napríklad pri aktualizácii jedného poľa zdroja môže byť posielanie úplnej reprezentácie zdroja ťažkopádne a využíva veľa zbytočnej šírky pásma. V takýchto prípadoch má sémantika PATCH oveľa väčší zmysel.

Ďalším dôležitým aspektom, ktorý je potrebné tu zvážiť, je idempotencia; PUT je idempotentné; PATCH môže byť, ale nevyžaduje sa. A teda - v závislosti od sémantiky operácie, ktorú implementujeme, si môžeme tiež zvoliť jednu alebo druhú na základe tejto charakteristiky.

3. Implementácia PUT a PATCH logiky

Povedzme, že chceme implementovať REST API pre aktualizáciu a HeavyResource s viacerými poľami:

verejná trieda HeavyResource {súkromné ​​celé číslo; súkromné ​​meno reťazca; súkromná adresa reťazca; // ...

Najprv musíme vytvoriť koncový bod, ktorý spracováva úplnú aktualizáciu prostriedku pomocou PUT:

@PutMapping ("/ heavyresource / {id}") public ResponseEntity saveResource (@RequestBody HeavyResource heavyResource, @PathVariable ("id") String id) {heavyResourceRepository.save (heavyResource, id); return ResponseEntity.ok ("zdroj uložený"); }

Toto je štandardný koncový bod pre aktualizáciu zdrojov.

Povedzme teraz, že pole s adresou bude klient často aktualizovať. V tom prípade, nechceme poslať celok HeavyResource objekt so všetkými poľami, ale my chceme možnosť iba aktualizovať adresa pole - metódou PATCH.

Môžeme vytvoriť HeavyResourceAddressOnly DTO, ktorý predstavuje čiastočnú aktualizáciu poľa adresy:

verejná trieda HeavyResourceAddressOnly {súkromné ​​celé číslo; súkromná adresa reťazca; // ...}

Ďalej môžeme využiť metódu PATCH na odoslanie čiastočnej aktualizácie:

@PatchMapping ("/ heavyresource / {id}") public ResponseEntity partialUpdateName (@RequestBody HeavyResourceAddressOnly partialUpdate, @PathVariable ("id") reťazec id) {heavyResourceRepository.save (čiastočnýUpdate, id); return ResponseEntity.ok ("adresa zdroja aktualizovaná"); }

S týmto podrobnejším DTO môžeme poslať iba pole, ktoré potrebujeme aktualizovať - ​​bez réžie odosielania vcelku HeavyResource.

Ak máme veľké množstvo týchto operácií čiastočnej aktualizácie, môžeme tiež preskočiť vytvorenie vlastného DTO pre každý výstup - a použiť iba mapu:

@RequestMapping (value = "/ heavyresource / {id}", method = RequestMethod.PATCH, consumes = MediaType.APPLICATION_JSON_VALUE) public ResponseEntity partialUpdateGeneric (@RequestBody aktualizácia máp, @PathVariable ("id") ID reťazca) {heavyResource ID) aktualizácie, id); return ResponseEntity.ok ("zdroj aktualizovaný"); }

Toto riešenie nám poskytne väčšiu flexibilitu pri implementácii API; Stratíme však tiež pár vecí - napríklad validáciu.

4. Testovanie PUT a PATCH

Na záver si napíšeme testy pre obe metódy HTTP. Najskôr chceme otestovať aktualizáciu celého zdroja pomocou metódy PUT:

mockMvc.perform (put ("/ heavyresource / 1") .contentType (MediaType.APPLICATION_JSON_VALUE) .content (objectMapper.writeValueAsString (nový HeavyResource (1, "Tom", "Jackson", 12, "rajská ulica"))))) .andExpect (status (). isOk ());

Vykonanie čiastočnej aktualizácie sa dosahuje pomocou metódy PATCH:

mockMvc.perform (patch ("/ heavyrecource / 1") .contentType (MediaType.APPLICATION_JSON_VALUE) .content (objectMapper.writeValueAsString (nový HeavyResourceAddressOnly (1, "5. avenue"))))). andExpect (status () () );

Môžeme tiež napísať test na všeobecnejší prístup:

Aktualizácie HashMap = nový HashMap (); updates.put ("adresa", "5. avenue"); mockMvc.perform (patch ("/ heavyresource / 1") .contentType (MediaType.APPLICATION_JSON_VALUE) .content (objectMapper.writeValueAsString (updates))) .andExpect (status (). isOk ()); 

5. Vybavovanie čiastočných požiadaviek pomocou Nulový Hodnoty

Keď píšeme implementáciu pre metódu PATCH, musíme určiť zmluvu, ako liečiť prípady, keď dostaneme nulový ako hodnota pre adresa pole v HeavyResourceAddressOnly.

Predpokladajme, že klient pošle nasledujúcu žiadosť:

{"id": 1, "address": null}

Potom to môžeme spracovať ako nastavenie hodnoty adresa pole do nulový alebo iba ignorovať takúto žiadosť tým, že ju zaobchádza ako s nezmenenou.

Mali by sme zvoliť jednu stratégiu riešenia nulový a toho sa držte pri každej implementácii metódy PATCH.

6. Záver

V tomto rýchlom výučbe sme sa zamerali na pochopenie rozdielov medzi metódami HTTP PATCH a PUT.

Implementovali sme jednoduchý radič Spring REST na aktualizáciu zdroja pomocou metódy PUT a čiastočnú aktualizáciu pomocou PATCH.

Implementáciu všetkých týchto príkladov a útržkov kódu nájdete v projekte GitHub - jedná sa o projekt Maven, takže by malo byť ľahké ho importovať a spustiť tak, ako je.


$config[zx-auto] not found$config[zx-overlay] not found