PATCH

Verwendung

Eine PATCH-Anfrage sendet eine Reihe von Anweisungen, die beschreiben, wie eine bestehende Ressource zu ändern ist. Anders als PUT, das die gesamte Ressource ersetzt, ändert PATCH nur die angegebenen Felder oder Eigenschaften.

Der Anfrage-Body enthält ein Patch-Dokument in einem Format, das der Server versteht. Der Content-Type-Header kennzeichnet das Patch-Format. Der Header Accept-Patch in Serverantworten gibt die unterstützten Patch-Formate bekannt.

Hinweis

PATCH ist nicht veraltet. Die Methode wurde 2010 standardisiert und ist nach wie vor ein aktiver Bestandteil der HTTP-Semantik. Verwirrung entsteht, weil PATCH später als andere Methoden hinzugefügt wurde und einige ältere Frameworks keine native Unterstützung bieten.

Hinweis

PATCH bietet keine Idempotenz-Garantien. Dasselbe Patch zweimal anzuwenden kann unterschiedliche Ergebnisse liefern (z. B. zweimaliges Anhängen an eine Liste). Gleichzeitige Patches auf dieselbe Ressource bergen ohne bedingte Anfragen (If-Unmodified-Since oder If-Match) das Risiko von Konflikten.

Gängige Patch-Formate

JSON Patch drückt Änderungen als geordnetes Array von Operationen aus: add, remove, replace, move, copy und test.

Content-Type: application/json-patch+json

[
  {"op":"replace","path":"/email",
   "value":"alice@example.re"},
  {"op":"add","path":"/verified","value":true}
]

JSON Merge Patch verfolgt einen einfacheren Ansatz. Das Patch-Dokument spiegelt die Struktur der Zielressource wider. Im Patch enthaltene Felder überschreiben bestehende Werte. Wird ein Feld auf null gesetzt, entfernt dies das Feld.

Content-Type: application/merge-patch+json

{"email":"alice@example.re","nickname":null}

Atomarität

Der Server wendet alle Änderungen eines Patch-Dokuments als eine einzige atomare Operation an. Schlägt eine Anweisung fehl, wird das gesamte Patch abgelehnt und die Ressource bleibt unverändert.

Hinweis

Eine PATCH-Anfrage hat Seiteneffekte und ist nicht garantiert idempotent. Zwei identische Patches, die nacheinander auf eine “An Liste anhängen”-Operation angewendet werden, erzeugen ein anderes Ergebnis als eine einmalige Anwendung.

JSON Merge Patch

Ein Client aktualisiert die E-Mail-Adresse von Benutzer 42 im Format JSON Merge Patch. Der Server wendet die Änderung an und gibt 200 OK mit der aktualisierten Ressource zurück.

Anfrage

PATCH /users/42 HTTP/1.1
Host: api.example.re
Content-Type: application/merge-patch+json
Content-Length: 28

{"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"}

JSON Patch

Ein Client wendet zwei Operationen auf eine Konfigurationsressource an: Er ersetzt das debug-Flag und fügt ein neues Feld für die Protokollierungsstufe hinzu. Der Server bestätigt mit 204 No Content.

Anfrage

PATCH /config/app HTTP/1.1
Host: api.example.re
Content-Type: application/json-patch+json
Content-Length: 102

[
  {"op":"replace","path":"/debug","value":false},
  {"op":"add","path":"/logLevel","value":"warn"}
]

Antwort

HTTP/1.1 204 No Content

Bedingtes Patch

Eine bedingte Anfrage mit If-Unmodified-Since verhindert die Änderung einer Ressource, die bereits von einem anderen Client geändert wurde. Wurde die Ressource nach dem angegebenen Zeitstempel geändert, gibt der Server 412 Precondition Failed zurück.

Anfrage

PATCH /docs/report.json HTTP/1.1
Host: api.example.re
Content-Type: application/merge-patch+json
If-Unmodified-Since: Mon, 01 Jan 2024 12:00:00 GMT
Content-Length: 21

{"status":"reviewed"}

Antwort

HTTP/1.1 412 Precondition Failed
Content-Length: 0

CORS

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

PATCH im Vergleich zu PUT

PATCH sendet nur die Änderungen, wodurch Anfragen kleiner und bei großen Ressourcen bandbreitenschonender werden. PUT sendet jedes Mal die vollständige Repräsentation, unabhängig davon, wie viele Felder sich geändert haben.

PUT ist idempotent. Dieselbe PUT-Anfrage zweimal zu senden führt zum selben Serverzustand. Bei PATCH ist Idempotenz nicht garantiert, da Operationen wie das Anhängen an eine Liste bei jeder Anwendung ein anderes Ergebnis erzeugen.

Verwenden Sie PATCH, wenn Sie bestimmte Felder einer bestehenden Ressource aktualisieren. Verwenden Sie PUT, wenn Sie die gesamte Ressource durch eine neue Repräsentation ersetzen.

PATCH im Vergleich zu POST

PATCH ändert eine bestehende Ressource unter einer bekannten URI. POST erstellt neue Ressourcen oder stößt eine serverseitige Verarbeitung an.

PATCH verwendet definierte Patch-Semantiken wie JSON Patch und JSON Merge Patch. POST überlässt die Semantik vollständig dem Server und schreibt kein Format für den Anfrage-Body vor.