HTTP PUT vs HTTP PATCH in a REST API

Overview

tässä nopeassa artikkelissa tarkastelemme eroja HTTP PUT-ja PATCH-verbien välillä sekä näiden kahden toiminnon semantiikkaa.

käytämme jousta toteuttaaksemme kaksi loppupistettä, jotka tukevat näitä kahta operaatiotyyppiä, ja ymmärtääksemme paremmin erot ja oikean tavan käyttää niitä.

milloin ja milloin laastari tulee käyttää?

aloitetaan yksinkertaisella ja hieman pelkistetyllä lauseella.

kun asiakkaan on korvattava olemassa oleva resurssi kokonaan, hän voi käyttää PUT: tä. Kun he tekevät osittaista päivitystä, he voivat käyttää HTTP-korjaustiedostoa.

esimerkiksi päivitettäessä resurssin yhtä kenttää, koko resurssin esittämisen lähettäminen voi olla hankalaa ja käyttää paljon tarpeetonta kaistanleveyttä. Tällaisissa tapauksissa laastarin semantiikka on paljon järkevämpää.

toinen tärkeä näkökohta tässä on idempotenssi; laita on idempotentti; laastari voi olla, mutta ei tarvitse. Ja, niin – riippuen semantiikasta operaation olemme toteuttamassa, voimme myös valita yhden tai toisen perustuu tähän ominaisuuteen.

Implementing PUT and PATCH Logic

Let ’ s say we want to implement the REST API for updating a heavy resource with multiple fields:

public class HeavyResource { private Integer id; private String name; private String address; // ...

Ensinnäkin meidän on luotava päätepiste, joka käsittelee resurssin täydellistä päivitystä PUT-ohjelmalla:

@PutMapping("/heavyresource/{id}")public ResponseEntity<?> saveResource(@RequestBody HeavyResource heavyResource, @PathVariable("id") String id) { heavyResourceRepository.save(heavyResource, id); return ResponseEntity.ok("resource saved");}

tämä on vakio päätetapahtuma resurssien päivittämisessä.

nyt sanotaan, että osoitekenttään tulee usein asiakas päivittämään. Siinä tapauksessa emme halua lähettää koko HeavyResource-objektia kaikilla kentillä, mutta haluamme mahdollisuuden päivittää osoitekentän vain PAIKKAUSMENETELMÄLLÄ.

voimme luoda raskaan Resurssilisäyksen vain DTO: n edustamaan osoitekentän osittaista päivitystä:

public class HeavyResourceAddressOnly { private Integer id; private String address; // ...}

Seuraava, voimme hyödyntää laastari menetelmä lähettää osittaisen päivityksen:

@PatchMapping("/heavyresource/{id}")public ResponseEntity<?> partialUpdateName( @RequestBody HeavyResourceAddressOnly partialUpdate, @PathVariable("id") String id) { heavyResourceRepository.save(partialUpdate, id); return ResponseEntity.ok("resource address updated");}

tämän rakeisempi DTO, voimme lähettää kentän meidän täytyy päivittää vain – ilman overhead lähettää koko Raskaat resurssit.

jos meillä on suuri määrä näitä osittaisia päivitysoperaatioita, voimme myös ohittaa mukautetun DTO: n luomisen jokaiselle ulos-ja käyttää vain karttaa:

@RequestMapping(value = "/heavyresource/{id}", method = RequestMethod.PATCH, consumes = MediaType.APPLICATION_JSON_VALUE)public ResponseEntity<?> partialUpdateGeneric( @RequestBody Map<String, Object> updates, @PathVariable("id") String id) { heavyResourceRepository.save(updates, id); return ResponseEntity.ok("resource updated");}

tämä ratkaisu antaa meille enemmän joustavuutta API: n toteuttamisessa; menetämme kuitenkin myös muutamia asioita – kuten validoinnin.

Testauspiste ja paikkaus

lopuksi kirjoitetaan testit molemmille HTTP-menetelmille. Ensin haluamme testata koko resurssin päivittämistä PUT-menetelmällä:

mockMvc.perform(put("/heavyresource/1") .contentType(MediaType.APPLICATION_JSON_VALUE) .content(objectMapper.writeValueAsString( new HeavyResource(1, "Tom", "Jackson", 12, "heaven street"))) ).andExpect(status().isOk());

osittainen päivitys suoritetaan PAIKKAUSMENETELMÄLLÄ:

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

voidaan myös kirjoittaa testi yleisemmälle lähestymistavalle:

HashMap<String, Object> updates = new HashMap<>();updates.put("address", "5th avenue");mockMvc.perform(patch("/heavyresource/1") .contentType(MediaType.APPLICATION_JSON_VALUE) .content(objectMapper.writeValueAsString(updates)) ).andExpect(status().isOk());

osittaisten pyyntöjen käsittely, joiden Null-arvo on

kun kirjoitamme toteutusta PAIKKAUSMENETELMÄLLE, meidän on määriteltävä sopimus siitä, miten käsitellä tapauksia, joissa saamme null: n arvona Osoitekentälle vain raskaassa Resurssilisässä.

Oletetaan, että asiakas lähettää seuraavan pyynnön:

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

sitten voimme käsitellä tätä asettamalla arvo osoitekentän nolla tai vain sivuuttaa tällaisen pyynnön käsittelemällä sitä ei-muutos.

meidän tulisi valita yksi strategia Nullin käsittelemiseksi ja pitää siitä kiinni jokaisessa LAASTARIMENETELMÄN toteutuksessa.

johtopäätös

tässä nopeassa opetusohjelmassa keskityimme HTTP-laastarin ja PUT-menetelmien erojen ymmärtämiseen.

toteutimme yksinkertaisen Spring REST-ohjaimen resurssin päivittämiseen PUT-menetelmällä ja osittaisen päivityksen patchilla.

kaikkien näiden esimerkkien ja koodinpätkien toteutus löytyy GitHub – projektista-tämä on Maven-projekti, joten sen tuonnin ja ajamisen pitäisi olla helppoa sellaisenaan.