Im RESTful-API-Design sind PUT und PATCH zwei HTTP-Methoden, die zum Aktualisieren von Ressourcen auf dem Server verwendet werden. Der Unterschied zwischen PUT und PATCH in REST-APIs besteht jedoch darin, wie sie die Aktualisierungen durchführen und in den Szenarien, in denen die einzelnen Methoden am besten geeignet sind. Beide Methoden dienen dazu, vorhandene Daten zu ändern. Das Verständnis der PUT- und PATCH-Unterschiede in der REST-API kann Entwicklern jedoch dabei helfen, die beste Wahl basierend auf der Art der Aktualisierung zu treffen, die sie durchführen müssen. In diesem Blog-Beitrag untersuchen wir den PUT- und PATCH-Unterschied in der REST-API. Dabei konzentrieren wir uns auf die Debatte zwischen PATCH und Update-REST, wann man sie jeweils verwenden sollte, und bieten Anleitungen zur Auswahl der richtigen Methode 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 wissen, was PUT überhaupt ist. Bezogen auf Abschnitt 9.6 RFC 2616, fordert die PUT-Methode in der REST-API an, dass die eingeschlossene Entität unter dem angegebenen Request-URI gespeichert wird.
Wenn der Anforderungs-URI auf eine bereits vorhandene Ressource verweist, SOLLTE die eingeschlossene Entität als modifizierte Version derjenigen betrachtet werden, die sich auf dem Ursprungsserver befindet. Wenn der Anforderungs-URI nicht auf eine vorhandene Ressource verweist und dieser URI vom anfordernden Benutzeragenten als neue Ressource definiert werden kann, kann der Ursprungsserver die Ressource mit diesem URI erstellen.
Mit anderen Worten: Die PUT-Methode wird verwendet, um eine gesamte Ressource auf dem Server zu aktualisieren. Dies macht PUT zu einem „vollständigeren“ Update, das häufig verwendet wird, wenn ein vollständiger Austausch der Ressource erforderlich ist.
Daher eignet sich PUT am besten für die folgenden Anwendungsfälle:
- Aktualisieren einer vollständigen Ressource (z. B. Aktualisieren eines Benutzerprofils mit allen neuen Informationen).
- Ersetzen eines gesamten Elements oder Datensatzes.
- Wenn die Identität der Ressource klar ist und ihre Daten vollständig aktualisiert werden müssen.
In Systemen wie Elasticsearch, sind idempotente Operationen notwendig, um die Datenkonsistenz zu gewährleisten. Wenn Sie beispielsweise ein Dokument in Elasticsearch mithilfe von PUT aktualisieren, wird sichergestellt, dass dieselbe Anforderung ohne unbeabsichtigte Nebenwirkungen wiederholt werden kann.
Was ist PATCH in REST-APIs?
Nachdem wir uns nun mit PUT in REST-APIs befasst haben, werfen wir einen Blick darauf, was PATCH in REST-APIs ist und wie es funktioniert, bevor wir PUT mit PATCH in REST-APIs vergleichen. Wie in definiert RFC 5789, fordert die PATCH-Methode in der REST-API an, dass eine Reihe von in der Anforderungsentität beschriebenen Änderungen auf die durch den Anforderungs-URI identifizierte Ressource angewendet werden.
Dies steht im Einklang mit der Unterscheidung zwischen PUT und PATCH REST API, bei der Sie nur die Daten senden, die geändert werden müssen, und der Server diese Änderungen auf die vorhandene Ressource anwendet, ohne die gesamte Ressource zu ändern. Entwickler erstellen häufig Patches, um diese inkrementellen Änderungen darzustellen und so eine minimale Datenübertragung und effiziente Updates sicherzustellen.
Aus diesem Grund eignet sich die PATCH-Methode in der REST-API besser für die folgenden Anwendungsfälle:
- Nur eine Teilmenge der Felder in einer Ressource aktualisieren (z. B. die E-Mail-Adresse oder Telefonnummer eines Benutzers ändern). Ein Beispiel für eine PATCH-API könnte darin bestehen, nur die neue E-Mail zu senden und andere Felder unberührt zu lassen.
- Verbesserung der Leistung durch Minimierung der Datennutzlast.
- Wenn Sie eine Ressource schrittweise aktualisieren möchten, anstatt sie vollständig zu ersetzen.
- Erstellen Sie Patches, um bestimmte Feldänderungen zu kapseln, z. B. die Änderung der E-Mail-Adresse eines Benutzers, ohne dass sich dies auf nicht verwandte Daten auswirkt.
Für Plattformen wie Headless-CMS die häufig komplexe Inhaltsstrukturen verarbeiten, kann die Verwendung von PATCH für kleinere Aktualisierungen – wie die Änderung eines einzelnen Felds – die Serverlast reduzieren und die Leistung verbessern.
Nachdem diese beiden Methoden behandelt wurden, sollten Sie 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 die Idempotenz in diesen beiden Methoden sprechen.
Idempotenz in PUT vs. Patch in REST-APIs
In REST-APIs bezieht sich Idempotenz auf die Eigenschaft einer Operation, die bei mehrmaliger Wiederholung mit denselben Eingaben zum gleichen Ergebnis führt. Das bedeutet, dass die mehrfache Ausführung derselben Anfrage dieselbe Auswirkung auf den Server haben sollte, unabhängig davon, wie oft sie ausgeführt wird. Dies ist wichtig, um Stabilität und Vorhersagbarkeit in einer API sicherzustellen. Aber welche Bedeutung hat es für den PUT- und PATCH-Unterschied in der REST-API?
PUT-Methode und Idempotenz
Die PUT-Methode in der REST-API ist immer idempotent, da sie darauf ausgelegt ist, die gesamte Ressource an einem angegebenen URI durch die in der Anfrage bereitgestellten Daten zu ersetzen. Mit anderen Worten: Wenn Sie eine PUT-Anfrage mehrmals mit denselben Ressourcendaten ausführen, ist das Ergebnis immer dasselbe.
Warum ist PUT idempotent? Wenn Sie eine PUT-Anfrage stellen, teilen Sie dem Server im Wesentlichen mit: „Dies ist der vollständige und genaue Status, den ich für diese Ressource haben möchte.“ Unabhängig davon, ob Sie die PUT-Anfrage einmal oder mehrmals stellen, ist die resultierende Ressource immer identisch.
Stellen Sie sich beispielsweise das Szenario vor, in dem Sie die E-Mail-Adresse eines Benutzers aktualisieren. Wenn Sie dieselbe PUT-Anfrage mehrmals stellen, ändert sich das Ergebnis nicht, da die Ressource jedes Mal durch dieselben Daten ersetzt wird.
Beispiel:
| PUT /users/1{„Benutzername“: „john_doe“, „email“: „[email protected]“} |
Wenn Sie diese Anfrage mehrmals senden, ist das Ergebnis immer dasselbe:
| {„Benutzername“: „john_doe“, „email“: „[email protected]“} |
Auch wenn es sich bei den Daten des Nutzers bereits um solche handelt, ändert ein erneutes Absenden der Anfrage nichts. Es ersetzt die Daten durch dieselben Daten, sodass die Wirkung der Anfrage gleich bleibt, unabhängig davon, wie oft sie wiederholt wird. Das macht PUT idempotent.
PATCH-Methode und Idempotenz
Die PATCH-Methode in der REST-API hingegen ist im Allgemeinen ebenfalls idempotent, jedoch mit mehr Flexibilität. Stellen Sie beim Erstellen von Patches sicher, dass die Vorgänge idempotent sind (z. B. das Festlegen eines Werts), um unbeabsichtigte Nebenwirkungen durch wiederholte Anforderungen zu vermeiden. Ob PATCH idempotent ist, hängt von der Operation und den zu ändernden Daten ab.
Warum ist PATCH idempotent? Bei PATCH-Anfragen bedeutet Idempotenz, dass die mehrmalige Anwendung desselben Patches zum gleichen Ergebnis führt. Dies gilt, solange der Patch selbst bei wiederholter Anwendung keine zusätzlichen Nebenwirkungen oder Veränderungen verursacht. Wenn Sie immer wieder das gleiche Pflaster mit den gleichen Daten anwenden, sollte das Ergebnis nach der ersten Anwendung unverändert sein.
Wenn Sie beispielsweise nur die E-Mail-Adresse eines Benutzers aktualisieren, ändert das wiederholte Senden derselben PATCH-Anfrage das Ergebnis nach dem ersten Mal nicht, selbst wenn die Anfrage mehrmals gestellt wird. Die E-Mail-Adresse des Benutzers bleibt dieselbe und der Status der Ressource ändert sich nicht.
Beispiel für eine PATCH-API:
| PATCH /users/1{“email“: „[email protected]“} |
Wenn die E-Mail-Adresse bereits [email protected] lautete, führt die erneute Anwendung dieses PATCH zu keiner Änderung, sodass sie idempotent wird.
Allerdings kann PATCH in manchen Fällen auch nicht-idempotent sein. Wenn beispielsweise eine PATCH-Operation einen Zähler ändert oder Elemente zu einer Liste hinzufügt (z. B. durch Erhöhen einer Zahl oder Anhängen an ein Array), können wiederholte Anwendungen desselben PATCHs zu unterschiedlichen Ergebnissen führen. Dies würde die Idempotenzeigenschaft verletzen.
Beispiel für einen nicht idempotenten API-REST-PATCH:
| PATCH /counter/1{“inkrementieren”: 1} |
Wenn Sie diesen PATCH wiederholt anwenden, erhöht sich der Zähler weiter, was jedes Mal zu anderen Werten führt. Dies ist nicht idempotent, da sich das Ergebnis mit jeder Anwendung ändert.
Nachdem Sie nun das Wesentliche kennen, können wir uns einige Beispielszenarien ansehen, um den Unterschied zwischen PUT und PATCH in REST-APIs besser zu verstehen.
Beispielszenarien: PUT vs. PATCH in REST-APIs
Abgesehen von der Theorie schauen wir uns den Unterschied zwischen PUT und PATCH anhand von Beispielen an, einschließlich idempotenter und nicht idempotenter Operationen.
Szenario 1: PUT-Anfrage – Ersetzen einer gesamten Ressource
Stellen Sie sich einen API-Endpunkt zur Verwaltung von Produkten in einem E-Commerce-System vor. Sie müssen alle Details eines Produkts aktualisieren, einschließlich Name, Preis und Beschreibung. Dies ist ein typisches Beispiel für die HTTP-Methode PUT vs. PATCH, bei der PUT verwendet wird, um die gesamte Produktressource zu ersetzen.
Ausgangsprodukt:
| GET /products/1001{„id“: 1001“, „name“: „Laptop“, „price“: 999,99, „description“: „Ein leistungsstarker Laptop.“} |
Sie möchten den Preis und die Beschreibung des Produkts aktualisieren. Sie senden eine PUT-Anfrage mit der gesamten Ressource:
PUT-Anfrage:
| PUT /products/1001{„id“: 1001, „name“: „Laptop“, „price“: 899,99, „description“: „Ein leistungsstarker Laptop zum Sonderpreis.“} |
Wenn Sie diese PUT-Anfrage einmal oder mehrmals stellen, ist das Ergebnis immer das gleiche. Die Produktdetails werden aktualisiert, um den neuen Preis und die neue Beschreibung widerzuspiegeln, und es wird jedes Mal das gleiche Ergebnis erzielt. Dies stellt die idempotente Natur von PUT sicher.
Ergebnis (nach PUT-Anfrage):
| {„id“: 1001, „name“: „Laptop“, „price“: 899,99, „description“: „Ein leistungsstarker Laptop zum Sonderpreis.“} |
Szenario 2: PATCH-Anfrage – Aktualisieren eines Teils einer Ressource
Betrachten wir nun eine PATCH-Anfrage zur Aktualisierung nur eines Teils der Produktdetails, beispielsweise der Beschreibung. Beispiel einer PATCH-API: Wenn Sie die Produktbeschreibung, aber nicht den Preis ändern möchten, ist PATCH die bessere Wahl. Um dies zu implementieren, würden Sie Patches erstellen, die nur die Felder enthalten, die geändert werden müssen, wie beispielsweise die Beschreibung in diesem API-REST-PATCH-Beispiel.
Ausgangsprodukt:
| GET /products/1001{„id“: 1001“, „name“: „Laptop“, „price“: 999,99, „description“: „Ein leistungsstarker Laptop.“} |
PATCH-Anfrage:
| PATCH /products/1001{“description“: „Ein leichter, leistungsstarker Laptop.“} |
Wenn Sie diese PATCH-Anfrage senden, wird nur das Beschreibungsfeld aktualisiert. Wenn Sie dieselbe PATCH-Anfrage mehrmals senden, bleibt die Beschreibung nach der ersten Aktualisierung unverändert, sodass die Anfrage idempotent ist.
Ergebnis (nach PATCH-Anfrage):
| {„id“: 1001, „name“: „Laptop“, „price“: 999,99, „description“: „Ein leichter, leistungsstarker Laptop.“} |
Wenn Sie denselben PATCH erneut anwenden, ist die Produktbeschreibung immer noch dieselbe wie nach dem ersten PATCH. Das Ergebnis ist konsistent, was PATCH in diesem Szenario idempotent macht.
Szenario 3: PATCH-Anfrage – Nicht-idempotenter Vorgang
Schauen wir uns eine nicht idempotente PATCH-Operation an. Angenommen, es gibt einen Endpunkt für das Wallet-Guthaben eines Benutzers und Sie möchten das Guthaben erhöhen. Ein Beispiel für den Unterschied zwischen PUT und PATCH kann hier veranschaulicht werden: PATCH fügt dem Kontostand jedes Mal einen Wert hinzu
Erstes Wallet:
| GET /users/1/wallet{“id“: 1“,balance“: 100,00} |
PATCH-Anfrage:
| PATCH /users/1/wallet{„Inkrement“: 50,00} |
Diese PATCH-Anfrage erhöht das Wallet-Guthaben um 50 $. Wenn Sie diese PATCH-Anfrage mehrmals senden, erhöht sich der Kontostand mit jedem PATCH weiter, was jedes Mal zu einem anderen Ergebnis führt. Dies ist nicht idempotent, da die wiederholte Anwendung desselben PATCHs zu einem anderen Ergebnis führt.
Ergebnis (nach der ersten PATCH-Anfrage):
| {„id“: 1, „balance“: 150,00} |
Ergebnis (nach der zweiten PATCH-Anfrage):
| {„id“: 1, „balance“: 200,00} |
Hier ist PATCH nicht idempotent, da wiederholte Anfragen mit denselben Daten zu unterschiedlichen Ergebnissen führen.
Zusammenfassung: Hauptunterschiede zwischen PUT und PATCH in REST-APIs
Der Hauptunterschied zwischen PUT und PATCH in der REST-API besteht darin, wie sie mit Aktualisierungen umgehen. PUT ersetzt die gesamte Ressource, sodass alle fehlenden Felder gelöscht werden, was zu Datenverlust führen kann. Aus diesem Grund erstellen Entwickler Patches für Teilaktualisierungen, um das Überschreiben unveränderter Felder zu vermeiden und die Datenintegrität aufrechtzuerhalten.
Dies macht PATCH bei Teilaktualisierungen effizienter. Ein Beispiel für eine PATCH-API ist: Wenn Sie nur die E-Mail-Adresse eines Benutzers aktualisieren möchten, würde beim Erstellen von Patches nur das E-Mail-Feld gesendet, im Gegensatz zu einer PUT-Anfrage, die die gesamten Benutzerdaten erfordern würde.
Bei PUT ist die volle Datennutzlast erforderlich. Das bedeutet, dass jedes Feld gesendet werden muss und alle fehlenden Felder gelöscht werden. PATCH sendet jedoch nur die Felder, die aktualisiert werden müssen, was es effizienter macht, insbesondere bei großen Ressourcen mit minimalen Änderungen. Die PATCH-Methode in der REST-API ermöglicht gezieltere und kleinere Anfragen und reduziert so die Datenübertragung.
Sowohl PUT als auch PATCH sind idempotent. Das bedeutet, dass die Wiederholung derselben Anfrage zum gleichen Ergebnis führt. Allerdings ist PUT vorhersehbarer, da es die gesamte Ressource ersetzt. Wenn PATCH zum Ändern nur bestimmter Felder verwendet wird, kann dies zu unterschiedlichen Ergebnissen führen, je nachdem, wie Aktualisierungen vom Server verarbeitet werden.
Wenn beispielsweise ein PATCH einen Zähler erhöht, können wiederholte Anfragen zu unterschiedlichen Ergebnissen führen. Dennoch können PATCH-API-Operationen auch idempotent gestaltet werden.
Zusammenfassend lässt sich sagen, dass der Unterschied zwischen PUT und PATCH in der REST-API auf die Art der Aktualisierungen zurückzuführen ist: PATCH ist für teilweise Änderungen vorgesehen, während PUT für den vollständigen Austausch von Ressourcen vorgesehen ist. Beide sind idempotent, PATCH kann jedoch komplexer sein.
Letzte Gedanken
Sowohl PUT als auch PATCH sind grundlegende HTTP-Methoden im REST-API-Design, sie dienen jedoch unterschiedlichen Zwecken, was den Kern des Unterschieds zwischen PUT und PATCH in der REST-API ausmacht. Sie können die Effizienz, Klarheit und Funktionalität Ihrer API erheblich verbessern, indem Sie den Unterschied zwischen PUT und PATCH anhand der Beispiele verstehen, die wir weiter oben in diesem Artikel behandelt haben. Durch die Auswahl der richtigen Methode (PATCH vs. Update-REST) basierend auf Ihrem Anwendungsfall können Sie Ihre API effizienter, wartbarer und benutzerfreundlicher gestalten. Berücksichtigen Sie immer die Art der Aktualisierung – ob vollständig oder teilweise – sowie die Auswirkungen auf die Leistung und Datenintegrität und wählen Sie die Methode aus, die Ihren Anforderungen am besten entspricht.
