HTTP PUT Method

Die HTTP-Methode PUT ersetzt die Ziel-Ressource vollständig mit dem Request-Body. Sie ist idempotent, wiederholte identische PUT-Requests haben denselben Effekt wie ein einzelner Request, und unterstützt sowohl Update als auch Creation (Upsert-Semantik).

Typ

HTTP-Methode

Syntax

PUT-Request mit vollständiger Ressourcen-URI und kompletten Ressourcen-Daten im Body.

http
PUT /api/users/42 HTTP/1.1
Host: api.example.com
Content-Type: application/json

Direktiven

Die Direktiven definieren PUT-Semantik und Response-Codes.

Request-Body
Enthält vollständige Ressourcen-Darstellung, ersetzt bestehende Ressource komplett.
200 OK
Ressource erfolgreich aktualisiert mit Response-Body der aktualisierten Ressource.
201 Created
Neue Ressource erstellt falls nicht existent, unterstützt Upsert-Pattern.
204 No Content
Erfolgreiche Aktualisierung ohne Response-Body, häufigste REST-Konvention.
409 Conflict
PUT-Request konfliktet mit aktuellem Resource-State, z.B. bei Constraints.
Idempotent
Mehrfache identische PUT-Requests produzieren identischen Server-State.
Complete Replacement
Fehlende Felder im PUT-Body werden auf Default-Werte gesetzt oder gelöscht.

Beispiele

Nachfolgend finden Sie praktische Anwendungsbeispiele für die PUT-Methode.

Beispiel 1 Complete Resource Update

http
PUT /api/users/alice HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer token_abc

{
  "id": "alice",
  "name": "Alice Schmidt",
  "email": "alice.new@example.com",
  "phone": "+49 123 456789",
  "role": "admin"
}

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

{
  "id": "alice",
  "name": "Alice Schmidt",
  "email": "alice.new@example.com",
  "phone": "+49 123 456789",
  "role": "admin",
  "updated_at": "2025-10-01T10:46:00Z"
}

Client ersetzt User-Ressource vollständig, alle Felder müssen im Request enthalten sein.

Beispiel 2 Upsert Pattern Creation

http
PUT /api/configs/production HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "environment": "production",
  "debug": false,
  "max_connections": 100
}

HTTP/1.1 201 Created
Location: /api/configs/production
Content-Type: application/json

{
  "environment": "production",
  "debug": false,
  "max_connections": 100,
  "created_at": "2025-10-01T10:46:00Z"
}

Config existiert nicht, PUT erstellt neue Ressource mit bekanntem ID (Upsert).

Beispiel 3 Idempotent Update with ETag

http
GET /api/documents/doc-42 HTTP/1.1
Host: api.example.com

HTTP/1.1 200 OK
ETag: "abc123"
Content-Type: application/json

{"title": "Draft", "content": "..."}

PUT /api/documents/doc-42 HTTP/1.1
Host: api.example.com
If-Match: "abc123"
Content-Type: application/json

{"title": "Final Version", "content": "..."}

HTTP/1.1 200 OK
ETag: "xyz789"

{"title": "Final Version", "content": "...", "version": 2}

Conditional PUT mit ETag verhindert Lost-Update-Problem bei konkurrierenden Änderungen.

PUT Idempotent Update Flow

PUT Idempotente Ressourcen-Ersetzung

Vorteile für die Systemarchitektur

  • Idempotenz: Retry-Safe bei Netzwerk-Fehlern, wiederholte Requests produzieren identischen State
  • Deterministische IDs: Client kann Ressourcen-IDs bestimmen für Client-Generated-ID Pattern
  • Upsert-Semantik: Unterstützt Create-or-Update Pattern für konfigurationsbasierte Ressourcen

Spezifikation

RFC 9110, Section 9.3.4 – HTTP Semantics https://www.rfc-editor.org/rfc/rfc9110.html#name-put

Weitere Spezifikationen

POST Method, PATCH Method, HTTP Status 200 - OK