PUT

De PUT-methode verzoekt dat de toestand van de doelbron wordt aangemaakt of vervangen door de toestand die wordt gedefinieerd door de representatie die wordt ingesloten in de payload van het verzoekbericht. Een succesvolle PUT van een gegeven representatie suggereert dat een volgende GET op dezelfde doelbron zal resulteren in een equivalente representatie die wordt verzonden in een 200 (OK) antwoord. Er is echter geen garantie dat een dergelijke toestandsverandering waarneembaar is, aangezien de doelbron tegelijkertijd door andere gebruikersagenten kan worden gebruikt, of onderworpen kan zijn aan dynamische verwerking door de origin server, voordat een volgende GET wordt ontvangen. Een succesvol antwoord houdt alleen in dat de bedoeling van de user agent is bereikt op het moment van verwerking door de origin server.

Als de doelbron geen huidige representatie heeft en de PUT er met succes een maakt, MOET de origin server de user agent informeren door een 201 (Created) antwoord te verzenden. Als de doelbron wel een huidige representatie heeft en die representatie met succes wordt gewijzigd in overeenstemming met de status van de ingesloten representatie, MOET de origin server een 200 (OK) of 204 (Geen inhoud) antwoord verzenden om aan te geven dat het verzoek met succes is voltooid.

Een origin server ZOU niet-herkende headervelden die in een PUT-verzoek worden ontvangen, moeten negeren (d.w.z., deze niet opslaan als onderdeel van de bronstatus).

Een origin server ZOU moeten controleren of de PUT-weergave consistent is met eventuele beperkingen die de server heeft voor de doelbron die niet kan of zal worden gewijzigd door de PUT. Dit is met name belangrijk wanneer de origin server interne configuratie-informatie met betrekking tot de URI gebruikt om de waarden voor representatiemetagegevens op GET-responses in te stellen. Wanneer een PUT representatie inconsistent is met de doelbron, DIENT de origin server deze consistent te maken, door de representatie te transformeren of de bronconfiguratie te wijzigen, of te antwoorden met een toepasselijk foutbericht dat voldoende informatie bevat om uit te leggen waarom de representatie ongeschikt is. De statuscodes 409 (Conflict) of 415 (Unsupported Media Type) worden voorgesteld, waarbij de laatste specifiek is voor beperkingen op Content-Type-waarden.

Als de doelbron bijvoorbeeld is geconfigureerd om altijd een Content-Type van "text/html" te hebben en de representatie die wordt PUT heeft een Content-Type van "image/jpeg", zou de origin server een van de volgende dingen moeten doen:

• a. de doelbron opnieuw configureren om het nieuwe mediatype weer te geven;
• b. de PUT-weergave transformeren naar een indeling die consistent is met die van de bron voordat deze wordt opgeslagen als de nieuwe bronstatus; of,
• c. het verzoek afwijzen met een 415 (Unsupported Media Type)-antwoord waarin wordt aangegeven dat de doelbron is beperkt tot "text/html", eventueel met een koppeling naar een andere bron die een geschikt doel zou zijn voor de nieuwe weergave.

HTTP definieert niet precies hoe een PUT-methode de status van een origin server beïnvloedt, afgezien van wat kan worden uitgedrukt door de intentie van het verzoek van de gebruikersagent en de semantiek van het antwoord van de origin server. Het definieert niet wat een bron zou kunnen zijn, in welke betekenis van dat woord dan ook, buiten de interface die via HTTP wordt geboden. Het definieert niet hoe bronstatus wordt "opgeslagen", noch hoe zulke opslag kan veranderen als gevolg van een verandering in bronstatus, noch hoe de origin server bronstatus vertaalt naar representaties. In het algemeen worden alle implementatiedetails achter de broninterface opzettelijk verborgen gehouden door de server.

Een origin server MOET GEEN validator headerveld (Sectie 7.2), zoals een ETag- of Last-Modified-veld, verzenden in een succesvol antwoord op PUT, tenzij de representatiegegevens van het verzoek zijn opgeslagen zonder dat er enige transformatie is toegepast op de body (d.w.z. de nieuwe representatiegegevens van de bron zijn identiek aan de representatiegegevens die zijn ontvangen in het PUT-verzoek) en de waarde van het validatorveld de nieuwe representatie weerspiegelt. Dankzij deze vereiste weet een gebruikersagent wanneer de representatie-instantie in het geheugen actueel blijft als gevolg van de PUT en dus niet opnieuw hoeft te worden opgehaald bij de origin server, en dat de nieuwe validator(s) die in het antwoord worden ontvangen, kunnen worden gebruikt voor toekomstige voorwaardelijke verzoeken om onbedoeld overschrijven te voorkomen (paragraaf 5.2).

Het fundamentele verschil tussen de POST- en PUT-methoden wordt benadrukt door de verschillende intentie voor de bijgevoegde representatie. De doelbron in een POST-verzoek is bedoeld om de ingesloten representatie af te handelen volgens de eigen semantiek van de bron, terwijl de ingesloten representatie in een PUT-verzoek wordt gedefinieerd als vervanging van de toestand van de doelbron. Daarom is de intentie van PUT idempotent en zichtbaar voor tussenpersonen, hoewel het exacte effect alleen bekend is bij de origin server.

Een juiste interpretatie van een PUT-verzoek veronderstelt dat de user agent weet welke doelbron gewenst is. Een dienst die namens de client een juiste URI selecteert na ontvangst van een verzoek dat van status verandert, ZOU geïmplementeerd moeten zijn met behulp van de POST-methode in plaats van de PUT-methode. Als de origin server de aangevraagde PUT-toestandswijziging niet uitvoert op de doelbron en deze in plaats daarvan op een andere bron wil toepassen, bijvoorbeeld wanneer de bron is verplaatst naar een andere URI, MOET de origin server een toepasselijk 3xx-antwoord (Redirection) verzenden; de user agent KAN dan zelf beslissen of het verzoek moet worden omgeleid of niet.

Een PUT-verzoek dat wordt toegepast op de doelbron kan neveneffecten hebben op andere bronnen. Een artikel kan bijvoorbeeld een URI hebben voor het identificeren van "de huidige versie" (een bron) die gescheiden is van de URI's die elke specifieke versie identificeren (verschillende bronnen die op een gegeven moment dezelfde status deelden als de bron van de huidige versie). Een succesvol PUT-verzoek op de URI voor de "huidige versie" kan daarom een nieuwe versiebron maken, naast het wijzigen van de status van de doelbron, en kan er ook voor zorgen dat links worden toegevoegd tussen de gerelateerde bronnen.

Een origin server die PUT op een bepaalde doelbron toestaat, MOET een 400-antwoord (Bad Request) sturen op een PUT-verzoek dat een headerveld Content-Range bevat (Sectie 4.2 van [RFC7233]), aangezien de payload waarschijnlijk gedeeltelijke inhoud is die ten onrechte is PUT als een volledige weergave. Gedeeltelijke inhoudsupdates zijn mogelijk door een afzonderlijk geïdentificeerde bron te benaderen met een status die een deel van de grotere bron overlapt, of door een andere methode te gebruiken die specifiek is gedefinieerd voor gedeeltelijke updates (bijvoorbeeld de PATCH-methode gedefinieerd in [RFC5789]).

Responses op de PUT-methode kunnen niet in de cache worden opgeslagen. Als een succesvol PUT-verzoek door een cache gaat die een of meer opgeslagen reacties heeft voor de effectieve URI van het verzoek, worden die opgeslagen reacties ongeldig gemaakt (zie paragraaf 4.4 van [RFC7234]).