PUT

PUT-metoden anmoder om, at målressourcens tilstand oprettes eller erstattes med den tilstand, der er defineret af den repræsentation, der er vedlagt i anmodningsmeddelelsens payload. En vellykket PUT af en given repræsentation antyder, at en efterfølgende GET på den samme målressource vil resultere i, at en tilsvarende repræsentation sendes i et 200 (OK) svar. Der er dog ingen garanti for, at en sådan tilstandsændring vil kunne observeres, da målressourcen kan blive behandlet af andre brugeragenter parallelt eller kan være genstand for dynamisk behandling af originalserveren, før et efterfølgende GET modtages. Et vellykket svar indebærer kun, at brugeragentens hensigt blev opnået på det tidspunkt, hvor den blev behandlet af originalserveren.

Hvis målressourcen ikke har en aktuel repræsentation, og PUT opretter en, SKAL originalserveren informere brugeragenten ved at sende et 201 (Created)-svar. Hvis målressourcen har en aktuel repræsentation, og denne repræsentation ændres i overensstemmelse med tilstanden for den vedlagte repræsentation, SKAL originalserveren sende enten et 200 (OK) eller et 204 (Intet indhold) svar for at angive, at anmodningen er gennemført.

En originalserver BØR ignorere ikke-genkendte headerfelter, der modtages i en PUT-anmodning (dvs, En originalserver BØR verificere, at PUT-repræsentationen er i overensstemmelse med eventuelle begrænsninger, som serveren har for målressourcen, og som ikke kan eller vil blive ændret af PUT. Dette er især vigtigt, når originalserveren bruger interne konfigurationsoplysninger relateret til URI'en for at indstille værdierne for repræsentationsmetadata på GET-svar. Når en PUT-repræsentation er inkonsistent med målressourcen, BØR originalserveren enten gøre dem konsistente ved at transformere repræsentationen eller ændre ressourcekonfigurationen eller svare med en passende fejlmeddelelse, der indeholder tilstrækkelig information til at forklare, hvorfor repræsentationen er uegnet. Statuskoderne 409 (Conflict) eller 415 (Unsupported Media Type) foreslås, hvor sidstnævnte er specifik for begrænsninger på Content-Type-værdier.

Hvis målressourcen for eksempel er konfigureret til altid at have en Content-Type på "text/html", og repræsentationen, der PUT'es, har en Content-Type på "image/jpeg", bør originalserveren gøre et af følgende:

• a. omkonfigurere målressourcen, så den afspejler den nye medietype;
• b. transformere PUT-repræsentationen til et format, der stemmer overens med ressourcens, før den gemmes som den nye ressourcetilstand; eller,
• c. afvise anmodningen med et 415 (Unsupported Media Type)-svar, der indikerer, at målressourcen er begrænset til "text/html", måske med et link til en anden ressource, der ville være et passende mål for den nye repræsentation.

HTTP definerer ikke nøjagtigt, hvordan en PUT-metode påvirker tilstanden på en originalserver ud over, hvad der kan udtrykkes af hensigten med brugeragentens anmodning og semantikken i originalserverens svar. Det definerer ikke, hvad en ressource kan være, i nogen betydning af dette ord, ud over den grænseflade, der leveres via HTTP. Den definerer ikke, hvordan ressourcestatus "lagres", eller hvordan en sådan lagring kan ændre sig som følge af en ændring i ressourcestatus, eller hvordan originalserveren oversætter ressourcestatus til repræsentationer. Generelt set er alle implementeringsdetaljer bag ressourceinterfacet med vilje skjult af serveren.

En originalserver MÅ IKKE sende et validatorheaderfelt (afsnit 7.2), såsom et ETag- eller Last-Modified-felt, i et vellykket svar på PUT, medmindre anmodningens repræsentationsdata blev gemt uden nogen transformation anvendt på kroppen (dvs. ressourcens nye repræsentationsdata er identiske med de repræsentationsdata, der blev modtaget i PUT-anmodningen), og validatorfeltets værdi afspejler den nye repræsentation. Dette krav gør det muligt for en brugeragent at vide, hvornår den repræsentationskrop, den har i hukommelsen, forbliver aktuel som et resultat af PUT, og dermed ikke behøver at blive hentet igen fra originalserveren, og at den eller de nye validatorer, der modtages i svaret, kan bruges til fremtidige betingede anmodninger for at forhindre utilsigtede overskrivninger (afsnit 5.2).

Den grundlæggende forskel mellem POST- og PUT-metoderne fremhæves af den forskellige hensigt med den vedlagte repræsentation. Målressourcen i en POST-anmodning er beregnet til at håndtere den vedlagte repræsentation i henhold til ressourcens egen semantik, mens den vedlagte repræsentation i en PUT-anmodning er defineret som erstatning for målressourcens tilstand. Derfor er hensigten med PUT idempotent og synlig for mellemmænd, selvom den nøjagtige effekt kun kendes af originalserveren.

En korrekt fortolkning af en PUT-anmodning forudsætter, at brugeragenten ved, hvilken målressource der ønskes. En tjeneste, der vælger en korrekt URI på vegne af klienten, efter at have modtaget en tilstandsændrende anmodning, BØR implementeres ved hjælp af POST-metoden i stedet for PUT. Hvis originalserveren ikke vil foretage den ønskede PUT-tilstandsændring på målressourcen og i stedet ønsker at anvende den på en anden ressource, f.eks. når ressourcen er blevet flyttet til en anden URI, SKAL originalserveren sende et passende 3xx-svar (omdirigering); brugeragenten KAN derefter træffe sin egen beslutning om, hvorvidt anmodningen skal omdirigeres eller ej.

En PUT-anmodning, der anvendes på målressourcen, kan have bivirkninger på andre ressourcer. For eksempel kan en artikel have en URI til at identificere "den aktuelle version" (en ressource), der er adskilt fra de URI'er, der identificerer hver enkelt version (forskellige ressourcer, der på et tidspunkt delte den samme tilstand som den aktuelle versionsressource). En vellykket PUT-anmodning på "den aktuelle versions" URI kan derfor oprette en ny versionsressource ud over at ændre målressourcens tilstand og kan også medføre, at der tilføjes links mellem de relaterede ressourcer.

En originalserver, der tillader PUT på en given målressource, SKAL sende et 400 (Bad Request)-svar på en PUT-anmodning, der indeholder et Content-Range-headerfelt (afsnit 4.2 i [RFC7233]), da nyttelasten sandsynligvis er delvist indhold, der fejlagtigt er blevet PUT som en fuld repræsentation. Delvise indholdsopdateringer er mulige ved at målrette en separat identificeret ressource med tilstand, der overlapper en del af den større ressource, eller ved at bruge en anden metode, der er specifikt defineret til delvise opdateringer (for eksempel PATCH-metoden defineret i [RFC5789]).

Svar på PUT-metoden kan ikke gemmes i cache. Hvis en vellykket PUT-anmodning passerer gennem en cache, der har et eller flere lagrede svar for den effektive anmodnings-URI, vil disse lagrede svar blive ugyldiggjort (se afsnit 4.4 i [RFC7234]).