2. Die PATCH-Methode (The PATCH Method)
2. Die PATCH-Methode (The PATCH Method)
Die PATCH-Methode fordert an, dass eine Reihe von Änderungen, die in der Request-Entity (request entity) beschrieben sind, auf die durch den Request-URI identifizierte Ressource angewendet werden. Diese Reihe von Änderungen wird in einem Format dargestellt, das als "Patch-Dokument (patch document)" bezeichnet wird und durch einen Medientyp (media type) identifiziert wird. Wenn der Request-URI nicht auf eine vorhandene Ressource zeigt, KANN (MAY) der Server eine neue Ressource erstellen, abhängig vom Patch-Dokumenttyp (ob er logischerweise eine Null-Ressource ändern kann) und den Berechtigungen usw.
Der Unterschied zwischen PUT- und PATCH-Anfragen spiegelt sich in der Art und Weise wider, wie der Server die enthaltene Entity verarbeitet, um die durch den Request-URI identifizierte Ressource zu ändern. In einer PUT-Anfrage wird die enthaltene Entity als geänderte Version der auf dem Ursprungsserver (origin server) gespeicherten Ressource betrachtet, und der Client fordert an, dass die gespeicherte Version ersetzt wird. Bei PATCH enthält die enthaltene Entity jedoch eine Reihe von Anweisungen (instructions), die beschreiben, wie eine Ressource, die sich derzeit auf dem Ursprungsserver befindet, geändert werden sollte, um eine neue Version zu erzeugen. Die PATCH-Methode betrifft die durch den Request-URI identifizierte Ressource, und sie KANN (MAY) auch Nebeneffekte (side effects) auf andere Ressourcen haben; das heißt, neue Ressourcen können erstellt oder vorhandene durch die Anwendung eines PATCH geändert werden.
PATCH ist weder sicher (safe) noch idempotent (idempotent), wie in [RFC2616], Abschnitt 9.1, definiert.
Eine PATCH-Anfrage kann so ausgegeben werden, dass sie idempotent ist, was auch dazu beiträgt, schlechte Ergebnisse durch Kollisionen (collisions) zwischen zwei PATCH-Anfragen auf derselben Ressource in einem ähnlichen Zeitrahmen zu verhindern. Kollisionen aus mehreren PATCH-Anfragen können gefährlicher sein als PUT-Kollisionen, da einige Patch-Formate von einem bekannten Basispunkt (base-point) aus arbeiten müssen, sonst beschädigen sie die Ressource. Clients, die diese Art von Patch-Anwendung verwenden, SOLLTEN (SHOULD) eine bedingte Anfrage (conditional request) verwenden, damit die Anfrage fehlschlägt, wenn die Ressource seit dem letzten Zugriff des Clients aktualisiert wurde. Beispielsweise kann der Client einen starken ETag [RFC2616] in einem If-Match-Header auf der PATCH-Anfrage verwenden.
Es gibt auch Fälle, in denen Patch-Formate nicht von einem bekannten Basispunkt aus arbeiten müssen (z. B. Hinzufügen von Textzeilen zu Protokolldateien oder nicht konfliktierenden Zeilen zu Datenbanktabellen), in diesem Fall ist dieselbe Sorgfalt in Client-Anfragen nicht erforderlich.
Der Server MUSS (MUST) die gesamte Reihe von Änderungen atomar (atomically) anwenden und niemals eine teilweise geänderte Darstellung (representation) bereitstellen (z. B. als Antwort auf ein GET während dieser Operation). Wenn das gesamte Patch-Dokument nicht erfolgreich angewendet werden kann, dann DARF (MUST NOT) der Server keine der Änderungen anwenden. Die Bestimmung dessen, was einen erfolgreichen PATCH darstellt, kann je nach Patch-Dokument und Art der geänderten Ressource(n) variieren. Beispielsweise kann das gängige 'diff'-Dienstprogramm ein Patch-Dokument generieren, das auf mehrere Dateien in einer Verzeichnishierarchie anwendbar ist. Die Atomaritätsanforderung gilt für alle vom Patch betroffenen Dateien, nicht nur für eine davon. Siehe "Fehlerbehandlung (Error Handling)", Abschnitt 2.2, für Details zu Statuscodes und möglichen Fehlerbedingungen.
Wenn die Anfrage einen Cache durchläuft und der Request-URI eine oder mehrere derzeit gecachte Entities identifiziert, SOLLTEN (SHOULD) diese Einträge als veraltet (stale) behandelt werden. Eine Antwort auf diese Methode ist nur cachefähig (cacheable), wenn sie explizite Frischeinformationen (freshness information) (wie einen Expires-Header oder eine "Cache-Control: max-age"-Direktive) sowie den Content-Location-Header enthält, der dem Request-URI entspricht, was anzeigt, dass der PATCH-Antwortkörper eine Ressourcendarstellung ist. Eine gecachte PATCH-Antwort kann nur verwendet werden, um auf nachfolgende GET- und HEAD-Anfragen zu antworten; sie DARF NICHT (MUST NOT) verwendet werden, um auf andere Methoden (wie PATCH) zu antworten.
Beachten Sie, dass Entity-Header (entity-headers), die in der Anfrage enthalten sind, nur für das enthaltene Patch-Dokument gelten und NICHT (MUST NOT) auf die geänderte Ressource angewendet werden dürfen. Daher könnte ein Content-Language-Header in der Anfrage vorhanden sein, aber er würde nur bedeuten (was auch immer das wert ist), dass das Patch-Dokument eine Sprache hat. Server SOLLTEN NICHT (SHOULD NOT) solche Header speichern, außer als Trace-Informationen (trace information), und SOLLTEN NICHT (SHOULD NOT) solche Header-Werte auf die gleiche Weise verwenden, wie sie bei PUT-Anfragen verwendet werden könnten. Daher spezifiziert dieses Dokument keine Methode zum Ändern des Content-Type- oder Content-Language-Werts eines Dokuments über Header, obwohl ein Mechanismus entworfen werden könnte, um dieses Ziel über ein Patch-Dokument zu erreichen.
Es gibt keine Garantie, dass eine Ressource mit PATCH geändert werden kann. Darüber hinaus wird erwartet, dass verschiedene Patch-Dokumentformate für verschiedene Arten von Ressourcen geeignet sind und dass kein einzelnes Format für alle Arten von Ressourcen geeignet ist. Daher gibt es kein einzelnes Standard-Patch-Dokumentformat, das Implementierungen unterstützen müssen. Server MÜSSEN (MUST) sicherstellen, dass ein empfangenes Patch-Dokument für den Typ der durch den Ziel-Request-URI identifizierten Ressource geeignet ist.
Clients müssen wählen, wann PATCH statt PUT verwendet werden soll. Wenn beispielsweise die Größe des Patch-Dokuments größer ist als die Größe der neuen Ressourcendaten, die in einem PUT verwendet würden, könnte es sinnvoll sein, PUT anstelle von PATCH zu verwenden. Ein Vergleich mit POST ist noch schwieriger, da POST auf sehr unterschiedliche Weise verwendet wird und PUT- und PATCH-ähnliche Operationen umfassen kann, wenn der Server dies wählt. Wenn die Operation die durch den Request-URI identifizierte Ressource nicht auf vorhersehbare Weise ändert, sollte POST anstelle von PATCH oder PUT in Betracht gezogen werden.