PUT

Verwendung

Eine PUT-Anfrage weist den Server an, die enthaltene Repräsentation unter der angegebenen URI zu speichern. Existiert die Ressource bereits, ersetzt der Server ihren gesamten Zustand durch die neue Repräsentation. Existiert unter der URI keine Ressource, legt der Server eine an.

Idempotenz

PUT ist idempotent. Dieselbe PUT-Anfrage mehrfach zu senden führt zum selben Serverzustand wie ein einmaliges Senden. Das steht im Gegensatz zu POST, bei dem wiederholte Übermittlungen doppelte Ressourcen anlegen oder eine Verarbeitung mehrfach auslösen.

Idempotenz macht es unbedenklich, PUT nach Netzwerkfehlern zu wiederholen. Ein Client, der nicht sicher ist, ob eine frühere Anfrage angekommen ist, sendet die Anfrage erneut, ohne unbeabsichtigte Seiteneffekte zu riskieren.

Inhaltsaushandlung

Der Server prüft die eingehende Repräsentation anhand seiner eigenen Vorgaben. Entspricht der Content-Type den Erwartungen und ist der Inhalt wohlgeformt, speichert der Server die Ressource und antwortet bei neuen Ressourcen mit 201 Created beziehungsweise bei Ersetzungen mit 200 OK / 204 No Content.

Ist der Medientyp nicht kompatibel, gibt der Server 415 Unsupported Media Type zurück. Eine 409-Conflict-Antwort weist auf einen Zustandskonflikt hin, der nichts mit dem Content-Type zu tun hat, etwa eine Versionsabweichung.

PUT im Vergleich zu POST

POST überlässt die Verarbeitung der Zielressource. PUT gibt die exakte URI an, unter der die Repräsentation abzulegen ist. Ein PUT auf /articles/42 speichert den Artikel unter /articles/42. Ein POST auf /articles fordert die Sammlung auf, einen neuen Artikel unter einer vom Server gewählten URI anzulegen.

PUT im Vergleich zu PATCH

PUT ersetzt die gesamte Ressource. PATCH wendet partielle Änderungen an. Ein einzelnes Feld mit PUT zu aktualisieren erfordert das Senden der vollständigen Repräsentation. PATCH sendet nur die Änderungen.

Eine Ressource erstellen

Ein Client speichert eine reine Textdatei unter /docs/setup.txt. Der Server erstellt die Ressource und antwortet mit 201 Created.

Anfrage

PUT /docs/setup.txt HTTP/1.1
Host: api.example.re
Content-Type: text/plain
Content-Length: 24

Install, configure, run.

Antwort

HTTP/1.1 201 Created
Location: /docs/setup.txt
Content-Length: 0

Eine Ressource ersetzen

Ein Client ersetzt eine bestehende JSON-Ressource unter /users/42. Der Server bestätigt die Aktualisierung mit 200 OK und gibt die gespeicherte Repräsentation zurück.

Anfrage

PUT /users/42 HTTP/1.1
Host: api.example.re
Content-Type: application/json
Content-Length: 43

{"name":"Alice","email":"alice@example.re"}

Antwort

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 51

{"id":42,"name":"Alice","email":"alice@example.re"}

Bedingte Aktualisierung

Eine bedingte Anfrage mit If-Match verhindert das Überschreiben einer Ressource, die von einem anderen Client geändert wurde. Der ETag-Wert stellt sicher, dass die Aktualisierung nur auf die erwartete Version angewendet wird.

Anfrage

PUT /config/app.json HTTP/1.1
Host: api.example.re
Content-Type: application/json
If-Match: "a1b2c3"
Content-Length: 27

{"debug":false,"port":8080}

Antwort

HTTP/1.1 204 No Content
ETag: "d4e5f6"

CORS

Ursprungsübergreifende PUT-Anfragen lösen immer einen CORS-Preflight aus. Der Browser sendet zuerst eine OPTIONS-Anfrage, um zu bestätigen, dass der Server PUT auf der Zielressource erlaubt.

Statuscodes der Antwort

201 Created zeigt an, dass der Server unter der Ziel-URI eine neue Ressource erstellt hat. Das gilt, wenn an dieser Stelle zuvor keine Ressource vorhanden war.

200 OK bestätigt, dass eine bestehende Ressource ersetzt wurde und die Antwort die aktualisierte Repräsentation im Body enthält.

204 No Content bestätigt eine Ersetzung ohne Antwort-Body. Das ist üblich, wenn der Client die gespeicherte Repräsentation nicht zurückgeliefert bekommen muss.

412 Precondition Failed zeigt an, dass die If-Match-Bedingung nicht erfüllt war. Der vom Client angegebene ETag-Wert stimmt nicht mit der aktuellen Ressourcenversion überein, weshalb der Server die Aktualisierung ablehnt, um Änderungen eines anderen Clients nicht zu überschreiben.

409 Conflict signalisiert einen Zustandskonflikt auf Anwendungsebene, der nichts mit Vorbedingungen zu tun hat, etwa einen inhaltlichen Merge-Konflikt oder eine Versionskontrollkollision, die der Client manuell auflösen muss.