PATCH request method
Die PATCH HTTP-Methode wendet teilweise Änderungen an einer Ressource an.
PATCH ist etwas analog zum Konzept der "Aktualisierung", das im CRUD vorkommt (allgemein 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 Änderung einer Ressource, während PUT einen vollständigen Ersatz der Ressource darstellt. Eine PUT-Anfrage ist immer idempotent (mehrmaliges Wiederholen der gleichen Anfrage führt dazu, dass die Ressource im gleichen Zustand bleibt), während eine PATCH-Anfrage nicht immer idempotent sein muss. Wenn beispielsweise eine Ressource einen automatisch inkrementierenden 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.
Ähnlich wie POST kann eine PATCH-Anfrage potenziell Nebenwirkungen auf andere Ressourcen haben.
Ein Server kann die Unterstützung für PATCH anzeigen, indem er es der Liste in den Allow oder Access-Control-Allow-Methods (für CORS) Antwort-Headern hinzufügt. Ein weiteres implizites Anzeichen dafür, dass PATCH unterstützt wird, ist der Accept-Patch Header (in der Regel 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 sein |
| Sicher | Nein |
| Idempotent | Nein |
| Cache-fähig | Nur wenn Frischeinformationen enthalten sind |
| In HTML-Formularen erlaubt | Nein |
Syntax
PATCH <request-target>["?"<query>] HTTP/1.1
<request-target>-
Identifiziert das Ziel der Anfrage in Kombination mit den Informationen im
Host-Header. Dies ist ein absoluter Pfad (z.B.,/path/to/file.html) bei Anfragen an einen Ursprungsserver und eine absolute URL bei Anfragen an Proxys (z.B.,http://www.example.com/path/to/file.html). <query>Optional-
Eine optionale Abfragekomponente, die durch ein Fragezeichen
?eingeleitet wird. Wird oft verwendet, um identifizierende Informationen in Form vonkey=valuePaaren zu übermitteln.
Beispiele
Erfolgreiche Änderung einer Ressource
Angenommen, es gibt eine Ressource auf dem Server, die einen Benutzer mit einer numerischen ID von 123 in folgendem Format darstellt:
{
"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 Feld status:
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ängen von der Implementierung ab. Der Erfolg kann durch jeden der erfolgreichen Antwort-Statuscodes angezeigt werden. In diesem Beispiel wird ein 204 No Content verwendet, da es nicht notwendig ist, einen Body mit zusätzlichen Kontextinformationen zur Operation zu übermitteln. Ein ETag wird bereitgestellt, damit der Anfragesteller eine bedingte Anfrage in der Zukunft durchführen kann:
HTTP/1.1 204 No Content
Content-Location: /users/123
ETag: "e0023aa4f"
Spezifikationen
| Spezifikation |
|---|
| RFC 5789 |
Browser-Kompatibilität
Der Browser verwendet die PATCH-Methode nicht für vom Benutzer initiierte Aktionen, daher ist "Browser-Kompatibilität" nicht anwendbar. Entwickler können diese Anfragemethode mit fetch() festlegen.
Siehe auch
- HTTP-Anfragemethoden
- HTTP-Antwortstatuscodes
- HTTP-Header
204Allow,Access-Control-Allow-MethodsHeaderAccept-Patch– spezifiziert die vom Server akzeptierten Patch-Dokumentformate- JSON Patch Generator