PUTpyynnöistä

PUT-pyynnöillä tarkoitetaan HTTP-pyyntöjä, joiden tavoitteena on asettaa tai korvata määritetty resurssi tietyllä URI-osoitteella. Pyyntö sisältää resurssin uuden tilan sen rungossa (yleensä JSON-, XML- tai muun muodossa). Kun palvelin käsittelee PUT-pyynnön, se pyrkii korvaamaan olemassa olevan resurssin tälle URI:lle tai, joissakin toteutuksissa, luomaan resurssin jos sitä ei vielä ole. PUT on määritelty osaksi HTTP/1.1 -asetuksia ja on idempotentti.

PUT on idempotentti: saman pyyntöparin toistaminen useaan kertaan johtaa samaan lopputulokseen kuin kerran toteutetulla pyynnöllä. Se ei ole turvallinen eikä pyyntöihi liittyy resurssin tilan muuttuminen; toisin sanoen se voi muuttaa palvelimen tilaa. PUT on tarkoitettu resurssin täydelliseen korvaamiseen; mikäli halutaan päivittää vain osa resurssista, suositellaan käyttämään PATCH-pyyntöä.

Käytäntö ja vastaukset: yleisimpiä palautusarvoja ovat 200 OK (paluu uuden tilan kanssa), 201 Created (resurssi luotiin), sekä 204 No Content (ei palautettavaa dataa). Jos resurssia ei voida käsitellä tai sitä ei löydetä, voidaan palauttaa 400, 404 tai muu virhekoodi. Konkurenssinhallintaan käytetään usein ETag-tunnisteita ja If-Match -otsikkoa; jos resurssin tilaa on muutettu toisen osapuolen toimesta, serveri voi vastata 412 Precondition Failed.

Yleisiä huomioita: PUT-pyynnöt soveltuvat API-tyyppiin, jossa resurssi on yksilöity URI:lla ja sen tila on tiedettävä kokonaisuudessaan ennen tallentamista. Ne voivat johtaa ylikirjoituksiin, joten on tärkeää dokumentoida käyttäjärajapinnan käytäntö ja huomioida autentikointi sekä oikeudet.

Esimerkki: PUT /articles/123 {"title":"Uusin otsikko","content":"Sisältö..."} Tämä palauttaa tilan, joka kuvaa kyseisen artikkelin uutta sisältöä.