PATCH request method

Die HTTP-Methode PATCH wendet teilweise Modifikationen auf eine Ressource an.

PATCH ist in gewisser Weise analog zum Konzept der "Aktualisierung", das im CRUD zu finden ist (im Allgemeinen ist HTTP anders als CRUD, und die beiden sollten nicht verwechselt werden).

Im Vergleich zu PUT dient ein PATCH als eine Reihe von Anweisungen zur Modifizierung einer Ressource, während PUT eine vollständige Ersetzung der Ressource darstellt. Eine PUT-Anfrage ist immer idempotent (das Wiederholen derselben Anfrage führt dazu, dass die Ressource im gleichen Zustand verbleibt), während eine PATCH-Anfrage nicht immer idempotent sein muss. Wenn z. B. eine Ressource einen Autoincrement-Zähler enthält, wird eine PUT-Anfrage den Zähler überschreiben (da sie die gesamte Ressource ersetzt), aber eine PATCH-Anfrage möglicherweise nicht.

Wie POST kann eine PATCH-Anfrage potenziell Seiteneffekte auf andere Ressourcen haben.

Ein Server kann Unterstützung für PATCH anzeigen, indem er es in die Liste der Allow oder Access-Control-Allow-Methods (für CORS) Antwort-Header aufnimmt. Ein weiteres implizites Anzeichen dafür, dass PATCH unterstützt wird, ist der Accept-Patch-Header (gewöhnlich nach einer OPTIONS-Anfrage zu einer Ressource), der die Medientypen auflistet, die der Server in einer PATCH-Anfrage für eine Ressource verstehen kann.

Anfrage hat einen Body Ja
Erfolgreiche Antwort hat einen Body Kann
Safe Nein
Idempotent Nein
Cacheable Nur wenn Frischeinformationen enthalten sind
Erlaubt in HTML-Formularen Nein

Syntax

http
PATCH <request-target>["?"<query>] HTTP/1.1
<request-target>

Identifiziert die Zielressource der Anfrage, wenn sie mit den im Host-Header bereitgestellten Informationen kombiniert wird. Dies ist ein absoluter Pfad (z. B. /path/to/file.html) bei Anfragen an einen Ursprung-Server und eine absolute URL bei Anfragen an Proxies (z. B. http://www.example.com/path/to/file.html).

<query> Optional

Ein optionaler Abfragekomponente, der durch ein Fragezeichen ? eingeleitet wird. Häufig verwendet, um Identifikationsinformationen in Form von key=value-Paaren zu übertragen.

Beispiele

Erfolgreiche Modifikation einer Ressource

Angenommen, auf dem Server gibt es eine Ressource, die einen Benutzer mit einer numerischen ID von 123 im folgenden Format darstellt:

json
{
  "firstName": "Example",
  "LastName": "User",
  "userId": 123,
  "signupDate": "2024-09-09T21:48:58Z",
  "status": "active",
  "registeredDevice": {
    "id": 1,
    "name": "personal",
    "manufacturer": {
      "name": "Hardware corp"
    }
  }
}

Anstatt ein JSON-Objekt zu senden, um eine Ressource vollständig zu überschreiben, ändert ein PATCH nur bestimmte Teile der Ressource. Diese Anfrage aktualisiert das status-Feld:

http
PATCH /users/123 HTTP/1.1
Host: example.com
Content-Type: application/json
Content-Length: 27
Authorization: Bearer ABC123

{
  "status": "suspended"
}

Die Interpretation und Authentifizierung der PATCH-Anfrage hängt von der Implementierung ab. Der Erfolg kann durch jeden der erfolgreichen Antwortstatuscodes angezeigt werden. In diesem Beispiel wird ein 204 No Content verwendet, da es nicht notwendig ist, einen Body mit zusätzlichen Kontextinformationen über die Operation zu übermitteln. Ein ETag wird bereitgestellt, damit der Anrufer eine bedingte Anfrage in Zukunft durchführen kann:

http
HTTP/1.1 204 No Content
Content-Location: /users/123
ETag: "e0023aa4f"

Spezifikationen

Specification
RFC 5789

Browser-Kompatibilität

Der Browser verwendet die PATCH-Methode nicht für vom Benutzer initiierte Aktionen, daher gilt "Browser-Kompatibilität" nicht. Entwickler können diese Anfragemethode mit fetch() einstellen.

Siehe auch