PUT

Die PUT-Methode verlangt, dass der Zustand der Zielressource erstellt oder durch den Zustand ersetzt wird, der durch die in der Nutzlast der Anforderungsnachricht enthaltene Darstellung definiert ist. Ein erfolgreiches PUT einer bestimmten Repräsentation würde bedeuten, dass ein anschließender GET auf dieselbe Zielressource zu einer äquivalenten Repräsentation führt, die in einer 200 (OK) Antwort gesendet wird. Es gibt jedoch keine Garantie dafür, dass eine solche Zustandsänderung beobachtet werden kann, da die Zielressource möglicherweise parallel von anderen User-Agents bearbeitet wird oder einer dynamischen Verarbeitung durch den Ursprungsserver unterliegt, bevor ein nachfolgender GET empfangen wird. Eine erfolgreiche Antwort bedeutet nur, dass die Absicht des Benutzeragenten zum Zeitpunkt der Verarbeitung durch den Ursprungsserver erreicht wurde.

Wenn die Zielressource keine aktuelle Darstellung hat und das PUT erfolgreich eine erstellt, dann MUSS der Ursprungsserver den Benutzeragenten durch Senden einer 201 (Created) Antwort informieren. Wenn die Zielressource eine aktuelle Repräsentation hat und diese Repräsentation erfolgreich in Übereinstimmung mit dem Zustand der beigefügten Repräsentation geändert wird, dann MUSS der Ursprungsserver entweder eine 200 (OK) oder eine 204 (No Content) Antwort senden, um den erfolgreichen Abschluss der Anfrage anzuzeigen.

Ein Ursprungsserver SOLLTE nicht erkannte Header-Felder, die in einer PUT-Anfrage empfangen werden, ignorieren (d.h., Ein Herkunftsserver SOLLTE überprüfen, ob die PUT-Darstellung mit allen Einschränkungen des Servers für die Zielressource konsistent ist, die durch das PUT nicht geändert werden können oder werden. Dies ist besonders wichtig, wenn der Ursprungsserver interne Konfigurationsinformationen in Bezug auf den URI verwendet, um die Werte für Darstellungsmetadaten in GET-Antworten festzulegen. Wenn eine PUT-Darstellung nicht mit der Zielressource übereinstimmt, SOLLTE der Ursprungsserver sie entweder durch Umwandlung der Darstellung oder Änderung der Ressourcenkonfiguration konsistent machen oder mit einer entsprechenden Fehlermeldung antworten, die genügend Informationen enthält, um zu erklären, warum die Darstellung ungeeignet ist. Vorgeschlagen werden die Statuscodes 409 (Conflict) oder 415 (Unsupported Media Type), wobei letzterer spezifisch für Einschränkungen der Content-Type-Werte ist.

Wenn die Zielressource beispielsweise so konfiguriert ist, dass sie immer einen Content-Type von "text/html" hat und die Darstellung, die PUT ist, einen Content-Type von "image/jpeg" hat, sollte der Ursprungsserver eine der folgenden Maßnahmen ergreifen:

• a. die Zielressource neu konfigurieren, um den neuen Medientyp widerzuspiegeln;
• b. die PUT-Darstellung in ein Format umwandeln, das mit dem der Ressource übereinstimmt, bevor es als neuer Ressourcenstatus gespeichert wird; oder,
• c. die Anfrage mit einer Antwort 415 (Unsupported Media Type) zurückweisen, die angibt, dass die Zielressource auf "text/html" beschränkt ist, vielleicht mit einem Link zu einer anderen Ressource, die ein geeignetes Ziel für die neue Darstellung wäre.

HTTP definiert nicht genau, wie eine PUT-Methode den Zustand eines Ursprungs-Servers beeinflusst, abgesehen von dem, was durch die Absicht der Anfrage des Benutzeragenten und die Semantik der Antwort des Ursprungs-Servers ausgedrückt werden kann. Es wird nicht definiert, was eine Ressource in irgendeinem Sinne dieses Wortes sein könnte, abgesehen von der über HTTP bereitgestellten Schnittstelle. Es wird weder definiert, wie der Zustand einer Ressource "gespeichert" wird, noch wie sich diese Speicherung infolge einer Änderung des Ressourcenzustands ändern kann, noch wie der Ursprungsserver den Ressourcenzustand in Darstellungen übersetzt. Im Allgemeinen werden alle Implementierungsdetails hinter der Ressourcenschnittstelle vom Server absichtlich verborgen.

Ein Ursprungsserver MUSS KEIN Validator-Header-Feld (Abschnitt 7.2), wie z. B. ein ETag- oder Last-Modified-Feld, in einer erfolgreichen PUT-Antwort senden, es sei denn, die Repräsentationsdaten der Anfrage wurden ohne jegliche auf den Body angewendete Transformation gespeichert (d. h., die neuen Repräsentationsdaten der Ressource sind identisch mit den in der PUT-Anfrage empfangenen Repräsentationsdaten) und der Wert des Validator-Feldes spiegelt die neue Repräsentation wider. Diese Anforderung ermöglicht es einem Benutzeragenten zu wissen, wann der Repräsentationskörper, den er im Speicher hat, als Ergebnis des PUT aktuell bleibt und somit nicht erneut vom Ursprungsserver abgerufen werden muss, und dass der/die neue(n) in der Antwort empfangene(n) Validator(en) für künftige bedingte Anfragen verwendet werden kann/können, um ein versehentliches Überschreiben zu verhindern (Abschnitt 5.2).

Der grundlegende Unterschied zwischen den POST- und PUT-Methoden wird durch die unterschiedliche Absicht für die beigefügte Repräsentation hervorgehoben. Die Zielressource in einer POST-Anforderung soll die eingeschlossene Repräsentation gemäß der eigenen Semantik der Ressource behandeln, während die eingeschlossene Repräsentation in einer PUT-Anforderung als Ersatz für den Zustand der Zielressource definiert ist. Daher ist die Absicht von PUT idempotent und für Vermittler sichtbar, auch wenn die genaue Auswirkung nur dem Ursprungsserver bekannt ist.

Die korrekte Interpretation einer PUT-Anfrage setzt voraus, dass der Benutzeragent weiß, welche Zielressource gewünscht wird. Ein Dienst, der nach Erhalt einer zustandsändernden Anfrage im Namen des Clients einen geeigneten URI auswählt, SOLLTE mit der POST-Methode und nicht mit PUT implementiert werden. Wenn der Ursprungsserver die angeforderte PUT-Zustandsänderung an der Zielressource nicht vornimmt und stattdessen wünscht, dass sie auf eine andere Ressource angewendet wird, z. B. wenn die Ressource in einen anderen URI verschoben wurde, dann MUSS der Ursprungsserver eine entsprechende 3xx-Antwort (Umleitung) senden; der User-Agent KANN dann selbst entscheiden, ob er die Anfrage umleitet oder nicht.

Eine auf die Zielressource angewendete PUT-Anfrage kann Nebeneffekte auf andere Ressourcen haben. Zum Beispiel könnte ein Artikel eine URI zur Identifizierung der "aktuellen Version" (eine Ressource) haben, die von den URIs getrennt ist, die jede einzelne Version identifizieren (verschiedene Ressourcen, die zu einem bestimmten Zeitpunkt den gleichen Status wie die Ressource der aktuellen Version hatten). Eine erfolgreiche PUT-Anforderung für den URI der "aktuellen Version" kann daher zusätzlich zur Änderung des Zustands der Zielressource eine neue Versionsressource erstellen und auch dazu führen, dass Links zwischen den zugehörigen Ressourcen hinzugefügt werden.

Ein Ursprungsserver, der PUT für eine bestimmte Zielressource zulässt, MUSS eine 400 (Bad Request)-Antwort auf eine PUT-Anforderung senden, die ein Content-Range-Header-Feld (Abschnitt 4.2 von [RFC7233]) enthält, da es sich bei der Nutzlast wahrscheinlich um Teilinhalte handelt, die fälschlicherweise als vollständige Darstellung gepostet wurden. Teilweise Inhaltsaktualisierungen sind möglich, indem man eine separat identifizierte Ressource mit einem Zustand anvisiert, der sich mit einem Teil der größeren Ressource überschneidet, oder indem man eine andere Methode verwendet, die speziell für partielle Aktualisierungen definiert wurde (z. B. die in [RFC5789] definierte PATCH-Methode).

Antworten auf die PUT-Methode sind nicht cachefähig. Wenn eine erfolgreiche PUT-Anfrage einen Cache durchläuft, der eine oder mehrere gespeicherte Antworten für den effektiven Anfrage-URI hat, werden diese gespeicherten Antworten ungültig gemacht (siehe Abschnitt 4.4 von [RFC7234]).