PUT

PUT-metoden ber om at målressursens tilstand opprettes eller erstattes med tilstanden som er definert av representasjonen som er vedlagt i nyttelasten i forespørselen. En vellykket PUT av en gitt representasjon tilsier at en påfølgende GET på den samme målressursen vil resultere i at en tilsvarende representasjon sendes i et 200 (OK)-svar. Det er imidlertid ingen garanti for at en slik tilstandsendring vil kunne observeres, siden målressursen kan bli behandlet av andre brukeragenter parallelt, eller kan være gjenstand for dynamisk behandling av opprinnelsesserveren, før en eventuell påfølgende GET blir mottatt. Et vellykket svar innebærer bare at brukeragentens intensjon ble oppnådd på tidspunktet for behandlingen av origin-serveren.

Hvis målressursen ikke har en gjeldende representasjon og PUT lykkes med å opprette en, MÅ origin-serveren informere brukeragenten ved å sende et 201-svar (Created). Hvis målressursen har en gjeldende representasjon og denne representasjonen endres i samsvar med tilstanden til den vedlagte representasjonen, MÅ origin-serveren sende enten et 200- (OK) eller et 204-svar (No Content) for å indikere at forespørselen er fullført.

En origin-server BØR ignorere ukjente header-felt som mottas i en PUT-forespørsel (dvs, en originalserver BØR kontrollere at PUT-representasjonen er i samsvar med eventuelle begrensninger serveren har for målressursen som ikke kan eller vil bli endret av PUT. Dette er spesielt viktig når opprinnelsesserveren bruker intern konfigurasjonsinformasjon knyttet til URI-en for å angi verdiene for representasjonsmetadata på GET-svar. Når en PUT-representasjon ikke stemmer overens med målressursen, BØR originalserveren enten gjøre dem konsistente ved å transformere representasjonen eller endre ressurskonfigurasjonen, eller svare med en passende feilmelding som inneholder tilstrekkelig informasjon til å forklare hvorfor representasjonen er uegnet. Statuskodene 409 (Conflict) eller 415 (Unsupported Media Type) er foreslått, der sistnevnte er spesifikk for begrensninger på Content-Type-verdier.

Hvis for eksempel målressursen er konfigurert til alltid å ha en Content-Type på "text/html" og representasjonen som PUT har en Content-Type på "image/jpeg", bør origin-tjeneren gjøre ett av følgende:

• a. rekonfigurere målressursen slik at den gjenspeiler den nye medietypen;
• b. transformere PUT-representasjonen til et format som samsvarer med ressursens før den lagres som den nye ressurstilstanden; eller,
• c. avvise forespørselen med et 415-svar (Unsupported Media Type) som indikerer at målressursen er begrenset til "text/html", eventuelt med en lenke til en annen ressurs som vil være et egnet mål for den nye representasjonen.

HTTP definerer ikke nøyaktig hvordan en PUT-metode påvirker tilstanden til en opprinnelsesserver utover det som kan uttrykkes av intensjonen i brukeragentens forespørsel og semantikken i opprinnelsesserverens svar. Den definerer ikke hva en ressurs kan være, i noen betydning av ordet, utover grensesnittet som tilbys via HTTP. Den definerer ikke hvordan ressurstilstanden "lagres", eller hvordan denne lagringen kan endres som følge av en endring i ressurstilstanden, eller hvordan opprinnelsesserveren oversetter ressurstilstanden til representasjoner. Generelt sett er alle implementeringsdetaljer bak ressursgrensesnittet tilsiktet skjult av serveren.

En origin-server MÅ IKKE sende et validatorheader-felt (avsnitt 7.2), for eksempel et ETag- eller Last-Modified-felt, i et vellykket svar på PUT, med mindre representasjonsdataene i forespørselen ble lagret uten noen form for transformasjon (dvs. at ressursens nye representasjonsdata er identiske med representasjonsdataene som ble mottatt i PUT-forespørselen) og validatorfeltets verdi gjenspeiler den nye representasjonen. Dette kravet gjør det mulig for en brukeragent å vite når representasjonskroppen den har i minnet, fortsatt er aktuell som følge av PUT, og dermed ikke trenger å hentes på nytt fra opprinnelsesserveren, og at de(n) nye validatoren(e) som mottas i svaret, kan brukes til fremtidige betingede forespørsler for å forhindre utilsiktet overskriving (avsnitt 5.2).

Den grunnleggende forskjellen mellom POST- og PUT-metodene understrekes av den ulike hensikten med den vedlagte representasjonen. Målressursen i en POST-forespørsel er ment å håndtere den vedlagte representasjonen i henhold til ressursens egen semantikk, mens den vedlagte representasjonen i en PUT-forespørsel er definert som en erstatning for målressursens tilstand. Derfor er hensikten med PUT idempotent og synlig for mellomledd, selv om den nøyaktige effekten bare er kjent av opprinnelsesserveren.

Riktig tolkning av en PUT-forespørsel forutsetter at brukeragenten vet hvilken målressurs som ønskes. En tjeneste som velger en riktig URI på vegne av klienten etter å ha mottatt en tilstandsendrende forespørsel, BØR implementeres ved hjelp av POST-metoden i stedet for PUT. Hvis opprinnelsesserveren ikke vil gjøre den forespurte PUT-tilstandsendringen på målressursen, men i stedet ønsker å bruke den på en annen ressurs, for eksempel når ressursen er flyttet til en annen URI, MÅ opprinnelsesserveren sende et passende 3xx-svar (Redirection); brukeragenten KAN deretter selv bestemme om forespørselen skal omdirigeres eller ikke.

En PUT-forespørsel som brukes på målressursen, kan ha bivirkninger på andre ressurser. En artikkel kan for eksempel ha en URI for å identifisere "gjeldende versjon" (en ressurs) som er atskilt fra URI-ene som identifiserer hver enkelt versjon (ulike ressurser som på et tidspunkt delte samme tilstand som ressursen for gjeldende versjon). En vellykket PUT-forespørsel på URI-en for "gjeldende versjon" kan derfor opprette en ny versjonsressurs i tillegg til å endre tilstanden til målressursen, og kan også føre til at det legges til lenker mellom de relaterte ressursene.

En origin-server som tillater PUT på en gitt målressurs, MÅ sende et 400-svar (Bad Request) på en PUT-forespørsel som inneholder et Content-Range-headerfelt (avsnitt 4.2 i [RFC7233]), siden nyttelasten sannsynligvis er delvis innhold som feilaktig har blitt PUT som en fullstendig representasjon. Delvise innholdsoppdateringer er mulig ved å rette seg mot en separat identifisert ressurs med en tilstand som overlapper en del av den større ressursen, eller ved å bruke en annen metode som er spesielt definert for delvise oppdateringer (for eksempel PATCH-metoden som er definert i [RFC5789]).

Svar på PUT-metoden kan ikke lagres i hurtigbufferen. Hvis en vellykket PUT-forespørsel går gjennom en hurtigbuffer som har ett eller flere lagrede svar for den aktuelle forespørsels-URI-en, vil disse lagrede svarene bli ugyldiggjort (se avsnitt 4.4 i [RFC7234]).