Im RESTful API Design sind PUT und PATCH zwei HTTP-Methoden, um Ressourcen auf dem Server zu aktualisieren. Der Unterschied zwischen PUT und PATCH in REST APIs liegt jedoch darin, wie die Aktualisierungen durchgeführt werden und in welchen Situationen jede Methode am besten geeignet ist. Beide Methoden dienen der Änderung bestehender Daten, doch wer den Unterschied zwischen PUT und PATCH in REST APIs versteht, kann je nach Art des Updates die bessere Wahl treffen. In diesem Beitrag beleuchten wir den Unterschied zwischen PUT und PATCH in REST APIs, gehen auf die Debatte PATCH vs. Update REST ein, erklären, wann welche Methode sinnvoll ist, und geben Orientierung für verschiedene Anwendungsfälle.
Was ist PUT in REST APIs?
Um den Unterschied zwischen PUT und PATCH in REST APIs zu verstehen, müssen wir zunächst klären, was PUT überhaupt ist. Laut Abschnitt 9.6 RFC 2616fordert die PUT-Methode in REST API-Anfragen, dass die mitgesendete Entität unter der angegebenen Request-URI gespeichert wird.
Verweist die Request-URI auf eine bereits vorhandene Ressource, SOLLTE die mitgesendete Entität als geänderte Version der auf dem Ursprungsserver gespeicherten Ressource behandelt werden. Zeigt die Request-URI auf keine vorhandene Ressource, und ist der User-Agent in der Lage, diese URI als neue Ressource zu definieren, kann der Ursprungsserver die Ressource unter dieser URI anlegen.
Die PUT-Methode wird also verwendet, um eine Ressource auf dem Server vollständig zu ersetzen. Das macht PUT zu einem "vollständigen" Update, das immer dann sinnvoll ist, wenn eine Ressource komplett neu geschrieben werden soll.
PUT eignet sich besonders für folgende Anwendungsfälle:
- Vollständige Aktualisierung einer Ressource (z. B. ein Nutzerprofil mit komplett neuen Daten überschreiben).
- Einen gesamten Eintrag oder Datensatz ersetzen.
- Wenn die Identität der Ressource eindeutig ist und ihre Daten vollständig neu gesetzt werden sollen.
In Systemen wie Elasticsearchsind idempotente Operationen notwendig, um Datenkonsistenz zu gewährleisten. Ein Dokument in Elasticsearch per PUT zu aktualisieren stellt beispielsweise sicher, dass dieselbe Anfrage mehrfach gesendet werden kann, ohne unerwünschte Nebeneffekte zu verursachen.
Was ist PATCH in REST APIs?
Nachdem wir PUT in REST APIs behandelt haben, schauen wir uns an, was PATCH in REST APIs bedeutet und wie es funktioniert, bevor wir PUT und PATCH in REST APIs direkt vergleichen. Laut RFC 5789fordert die PATCH-Methode in REST API, dass eine Reihe von Änderungen, die in der Anfrage-Entität beschrieben sind, auf die durch die Request-URI identifizierte Ressource angewendet werden.
Das spiegelt den Unterschied zwischen PUT und PATCH in REST API wider: Es werden nur die Daten gesendet, die geändert werden sollen, und der Server wendet diese Änderungen auf die vorhandene Ressource an, ohne sie vollständig zu überschreiben. Entwickler arbeiten dabei häufig mit Patches, die genau diese inkrementellen Änderungen abbilden, um den Datenübertragungsaufwand gering und Updates effizient zu halten.
Deshalb eignet sich die PATCH-Methode in REST API besser für folgende Anwendungsfälle:
- Nur bestimmte Felder einer Ressource aktualisieren (z. B. die E-Mail-Adresse oder Telefonnummer eines Nutzers ändern). Ein PATCH-API-Beispiel könnte darin bestehen, nur die neue E-Mail zu senden und alle anderen Felder unverändert zu lassen.
- Die Performance verbessern, indem die Datenmenge pro Anfrage reduziert wird.
- Wenn eine Ressource schrittweise aktualisiert werden soll, anstatt sie komplett zu ersetzen.
- Patches erstellen, die gezielte Feldänderungen kapseln, etwa das Ändern der E-Mail-Adresse eines Nutzers, ohne andere Daten zu beeinflussen.
Für Plattformen wie Headless CMS die häufig komplexe Inhaltsstrukturen verwalten, kann PATCH bei kleineren Updates, wie der Änderung eines einzelnen Feldes, die Serverlast senken und die Performance verbessern.
Mit diesen beiden Methoden im Überblick solltest du eine gute Vorstellung davon haben, was PUT und PATCH in REST APIs sind. Bevor wir jedoch auf den Unterschied zwischen PUT und PATCH in REST APIs eingehen, müssen wir über Idempotenz bei diesen beiden Methoden sprechen.
Idempotenz bei PUT vs. PATCH in REST APIs
In REST APIs beschreibt Idempotenz die Eigenschaft einer Operation, bei der wiederholte Ausführungen mit denselben Eingaben immer dasselbe Ergebnis liefern. Das bedeutet: Dieselbe Anfrage kann beliebig oft gesendet werden, ohne dass sich der Zustand des Servers ändert. Das ist entscheidend für Stabilität und Vorhersehbarkeit in einer API. Aber was hat das mit dem Unterschied zwischen PUT und PATCH in REST API zu tun?
PUT-Methode und Idempotenz
Die PUT-Methode in REST API ist immer idempotent, da sie darauf ausgelegt ist, die gesamte Ressource unter einer bestimmten URI durch die Daten aus der Anfrage zu ersetzen. Anders gesagt: Wenn du eine PUT-Anfrage mehrfach mit denselben Ressourcendaten sendest, ist das Ergebnis jedes Mal identisch.
Warum ist PUT idempotent? Mit einer PUT-Anfrage teilst du dem Server im Wesentlichen mit: "Das ist der vollständige und genaue Zustand, den ich für diese Ressource möchte." Ob du die Anfrage einmal oder hundert Mal sendest, die resultierende Ressource bleibt immer gleich.
Stell dir zum Beispiel vor, du aktualisierst die E-Mail-Adresse eines Nutzers. Wenn du dieselbe PUT-Anfrage mehrfach sendest, ändert sich das Ergebnis nicht, weil die Ressource jedes Mal durch dieselben Daten ersetzt wird.
Beispiel:
| PUT /users/1{"username": "john_doe","email": "[email protected]"} |
Wenn du diese Anfrage mehrfach sendest, ist das Ergebnis immer dasselbe:
| {"username": "john_doe","email": "[email protected]"} |
Selbst wenn die Nutzerdaten bereits diesen Werten entsprechen, ändert ein erneutes Senden der Anfrage nichts. Die Daten werden durch dieselben Daten ersetzt, der Effekt bleibt also unabhängig von der Anzahl der Wiederholungen gleich. Das macht PUT idempotent.
PATCH-Methode und Idempotenz
Die PATCH-Methode in REST API ist im Allgemeinen ebenfalls idempotent, bietet aber mehr Flexibilität. Achte beim Erstellen von Patches darauf, dass die Operationen idempotent sind (z. B. das Setzen eines Werts), um unerwünschte Nebeneffekte durch wiederholte Anfragen zu vermeiden. Ob PATCH idempotent ist, hängt von der jeweiligen Operation und den geänderten Daten ab.
Warum ist PATCH idempotent? Bei PATCH-Anfragen bedeutet Idempotenz, dass das mehrfache Anwenden desselben Patches immer dasselbe Ergebnis liefert. Das gilt, solange der Patch bei wiederholter Anwendung keine zusätzlichen Nebeneffekte oder Änderungen verursacht. Wenn du denselben Patch mit denselben Daten wiederholt anwendest, sollte sich der Zustand nach der ersten Anwendung nicht mehr verändern.
Wenn du beispielsweise nur die E-Mail-Adresse eines Nutzers aktualisierst, ändert sich das Ergebnis nach dem ersten Mal nicht mehr, egal wie oft du dieselbe PATCH-Anfrage sendest. Die E-Mail-Adresse bleibt gleich, und der Zustand der Ressource ändert sich nicht.
PATCH API Beispiel:
| PATCH /users/1{"email": "[email protected]"} |
Wenn die E-Mail-Adresse bereits [email protected] war, bewirkt das erneute Anwenden dieses PATCH keine Änderung. Die Anfrage ist damit idempotent.
PATCH kann jedoch in manchen Fällen auch nicht-idempotent sein. Wenn eine PATCH-Operation etwa einen Zähler erhöht oder Elemente zu einer Liste hinzufügt (z. B. eine Zahl inkrementiert oder an ein Array anhängt), können wiederholte Anwendungen desselben PATCH zu unterschiedlichen Ergebnissen führen. Das verstößt gegen die Idempotenz-Eigenschaft.
Nicht-idempotentes API REST PATCH Beispiel:
| PATCH /counter/1{"increment": 1} |
Wenn du diesen PATCH wiederholt anwendest, steigt der Zähler weiter an und liefert jedes Mal einen anderen Wert. Das ist nicht idempotent, weil sich das Ergebnis mit jeder Anwendung ändert.
Jetzt, wo du die Grundlagen kennst, schauen wir uns einige Beispielszenarien an, um den Unterschied zwischen PUT und PATCH in REST APIs besser zu verstehen.
Beispielszenarien: PUT vs. PATCH in REST APIs
Theorie beiseite. Sehen wir uns den Unterschied zwischen PUT und PATCH anhand von Beispielen an, sowohl für idempotente als auch nicht-idempotente Operationen.
Szenario 1: PUT-Anfrage - Vollständiges Ersetzen einer Ressource
Stell dir einen API-Endpunkt zur Verwaltung von Produkten in einem E-Commerce-System vor. Du musst alle Details eines Produkts aktualisieren, einschließlich Name, Preis und Beschreibung. Das ist ein typisches Beispiel für die Methode HTTP mit PUT vs. PATCH, bei dem PUT verwendet wird, um die gesamte Produktressource zu ersetzen.
Ausgangsprodukt:
| GET /products/1001{"id": 1001,"name": "Laptop","price": 999.99,"description": "A powerful laptop."} |
Du möchtest Preis und Beschreibung des Produkts aktualisieren. Dazu sendest du einen PUT-Request mit der vollständigen Ressource:
PUT-Anfrage:
| PUT /products/1001{"id": 1001,"name": "Laptop","price": 899.99,"description": "A discounted powerful laptop."} |
Egal ob du diesen PUT-Request einmal oder mehrmals sendest – das Ergebnis bleibt immer gleich. Die Produktdetails werden mit dem neuen Preis und der neuen Beschreibung aktualisiert, und zwar identisch bei jedem Aufruf. Genau das macht PUT idempotent.
Ergebnis (nach PUT-Anfrage):
| {"id": 1001,"name": "Laptop","price": 899.99,"description": "Ein vergünstigter leistungsstarker Laptop."} |
Szenario 2: PATCH-Request – Teilaktualisierung einer Ressource
Betrachten wir nun eine PATCH-Anfrage zum teilweisen Aktualisieren von Produktdetails, beispielsweise der Beschreibung. PATCH API Beispiel: Wenn du nur die Produktbeschreibung ändern möchtest, nicht aber den Preis, ist PATCH die bessere Wahl. Dazu erstellst du einen Patch, der ausschließlich die zu ändernden Felder enthält, in diesem Fall die Beschreibung in diesem API REST PATCH-Beispiel.
Ausgangsprodukt:
| GET /products/1001{"id": 1001,"name": "Laptop","price": 999.99,"description": "A powerful laptop."} |
PATCH-Anfrage:
| PATCH /products/1001{"description": "A lightweight, powerful laptop."} |
Wenn du diese PATCH-Anfrage sendest, wird nur das Feld description aktualisiert. Sendest du dieselbe PATCH-Anfrage mehrmals, bleibt die description nach dem ersten Update unverändert. Das macht die Anfrage idempotent.
Ergebnis (nach PATCH-Anfrage):
| {"id": 1001,"name": "Laptop","price": 999.99,"description": "Ein leichter, leistungsstarker Laptop."} |
Wenn du denselben PATCH erneut anwendest, bleibt die Produktbeschreibung identisch mit dem Ergebnis nach dem ersten PATCH. Das Ergebnis ist konsistent – PATCH verhält sich in diesem Szenario also idempotent.
Szenario 3: PATCH-Anfrage – Nicht-idempotente Operation
Sehen wir uns eine nicht-idempotente PATCH-Operation an. Angenommen, es gibt einen Endpunkt für das Guthaben einer Nutzerbrieftasche, und du möchtest dieses Guthaben erhöhen. Ein anschaulicher Unterschied zwischen PUT und PATCH zeigt sich hier: PATCH addiert bei jedem Aufruf einen Wert zum Guthaben hinzu
Startguthaben:
| GET /users/1/wallet{"id": 1,"balance": 100.00} |
PATCH-Anfrage:
| PATCH /users/1/wallet{"increment": 50.00} |
Diese PATCH-Anfrage erhöht das Wallet-Guthaben um 50 $. Wird dieselbe PATCH-Anfrage mehrfach gesendet, steigt das Guthaben mit jeder Anfrage weiter an – das Ergebnis unterscheidet sich also bei jedem Aufruf. Damit ist PATCH nicht idempotent: Dieselbe Anfrage führt bei wiederholter Ausführung zu einem anderen Ergebnis.
Ergebnis (nach dem ersten PATCH-Request):
| {"id": 1,"balance": 150.00} |
Ergebnis (nach dem zweiten PATCH-Request):
| {"id": 1,"balance": 200.00} |
Hier ist PATCH nicht idempotent, weil wiederholte Anfragen mit denselben Daten unterschiedliche Ergebnisse liefern.
Zusammenfassung: Wesentliche Unterschiede zwischen PUT und PATCH in REST APIs
Der wesentliche Unterschied zwischen PUT und PATCH in REST API liegt darin, wie sie mit Aktualisierungen umgehen. PUT ersetzt die gesamte Ressource, sodass fehlende Felder gelöscht werden, was zu Datenverlust führen kann. Deshalb setzen Entwickler PATCH für partielle Aktualisierungen ein, um unveränderte Felder nicht zu überschreiben und die Datenintegrität zu wahren.
Das macht PATCH effizienter für partielle Aktualisierungen. Ein PATCH-API-Beispiel: Wenn Sie nur die E-Mail-Adresse eines Nutzers aktualisieren möchten, sendet PATCH ausschließlich das E-Mail-Feld, während eine PUT-Anfrage den gesamten Datensatz des Nutzers erfordern würde.
Bei PUT muss die vollständige Datenlast übermittelt werden. Das bedeutet, jedes Feld muss gesendet werden, und fehlende Felder werden gelöscht. PATCH hingegen sendet nur die Felder, die aktualisiert werden sollen, was es effizienter macht, besonders bei großen Ressourcen mit wenigen Änderungen. Die PATCH-Methode in REST API ermöglicht kleinere, gezieltere Anfragen und reduziert den Datenübertragungsaufwand.
Sowohl PUT als auch PATCH sind idempotent. Das bedeutet, dass die Wiederholung derselben Anfrage stets zum gleichen Ergebnis führt. PUT ist dabei vorhersehbarer, da es die gesamte Ressource ersetzt. PATCH, wenn es nur bestimmte Felder ändert, kann je nach serverseitiger Verarbeitung zu unterschiedlichen Ergebnissen führen.
Wenn ein PATCH beispielsweise einen Zähler erhöht, können wiederholte Anfragen zu unterschiedlichen Ergebnissen führen. PATCH-API-Operationen lassen sich jedoch auch idempotent gestalten.
Zusammenfassend lässt sich der Unterschied zwischen PUT und PATCH in REST API auf die Art der Aktualisierung reduzieren: PATCH ist für partielle Änderungen, PUT für den vollständigen Ersatz einer Ressource. Beide sind idempotent, aber PATCH kann komplexer sein.
Fazit
PUT und PATCH sind grundlegende HTTP-Methoden im REST API-Design und dienen unterschiedlichen Zwecken, was den Kern des Unterschieds zwischen PUT und PATCH in REST API ausmacht. Wenn Sie den Unterschied zwischen PUT und PATCH anhand der in diesem Artikel behandelten Beispiele verstehen, können Sie die Effizienz, Klarheit und Funktionalität Ihrer API deutlich verbessern. Wählen Sie die passende Methode (PATCH vs. REST-Update) je nach Anwendungsfall, um Ihre API effizienter, wartbarer und benutzerfreundlicher zu gestalten. Berücksichtigen Sie stets, ob es sich um eine vollständige oder partielle Aktualisierung handelt, welche Auswirkungen sie auf Leistung und Datenintegrität hat, und wählen Sie die Methode, die Ihren Anforderungen am besten entspricht.
