Alex - stock.adobe.com
Die wichtigsten HTTP-Methoden für die REST-API-Entwicklung
Diese fünf HTTP-Methoden sind zentral für die REST-API-Entwicklung. Verwenden Sie diesen Leitfaden, um die Unterschiede und Verwendungszwecke der einzelnen Methoden zu verstehen.
HTTP-basierte APIs lassen sich leicht in RESTful-Webdienste integrieren, aber sie erscheinen oft unlogisch, überlappend und ineffizient. Es gibt viele Möglichkeiten, HTTP-Methoden zu verwenden, von denen viele nicht mit den RESTful-Prinzipien vereinbar sind. Außerdem wird seit langem darüber diskutiert, wie wichtig es ist, beim Aufbau von APIs die REST- oder HTTP-Prinzipien strikt zu befolgen.
Daher ist es wichtig, die HTTP-API-Methoden zu überprüfen und zu verstehen, wie sie angemessen für Ressourcen und Ressourcensammlungen verwendet werden können. Werfen wir einen kurzen Blick auf den Hauptunterschied zwischen Ressourcen und Ressourcensammlungen und untersuchen dann die fünf grundlegenden HTTP-Methoden, die jeder kennen sollte, der sich mit der Entwicklung von RESTful APIs beschäftigt.
HTTP-Ressourcen versus Ressourcensammlungen
Eine HTTP-Ressource ist mit einer Datendatei vergleichbar: Entwickler können den Inhalt der Ressource lesen und aktualisieren, und sie wird auf einem Server gehostet und ist über eine URL adressierbar. Eine Ressourcensammlung ist ein Satz zusammengehöriger Ressourcen, der als ein Satz zusammengehöriger Dateien betrachtet werden kann. Die Methoden, die wir in diesem Beitrag untersuchen, können auf Ressourcen, Ressourcensammlungen oder beides angewendet werden.
Die Beziehung zwischen den Ressourcen innerhalb einer Sammlung hängt von der Software ab, die die Sammlung unterstützt - genauer gesagt, von der Implementierung dieser Software. Die Dateien können verkettet, in einem Baum angeordnet oder auf jede andere Weise geordnet sein. Wenn die Implementierungen dem Client-Verhalten keine vorgegebene Reihenfolge zuweisen, kann die daraus resultierende Vielfalt zu Unstimmigkeiten führen und Anwendungen zum Absturz bringen.
Methode 1: POST
POST ist die einzige HTTP-Methode der RESTful API, die in erster Linie mit Ressourcensammlungen arbeitet. Bei der Erstellung einer untergeordneten Ressource in einer Sammlung wird durch die Anwendung von POST auf die übergeordnete Ressource eine neue Ressource erstellt, mit der richtigen Hierarchie verknüpft und eine spezielle URL für eine spätere Referenz zurückgegeben. Beachten Sie jedoch, dass POST nicht idempotent ist. Sie können diese Methode nicht mehr als einmal verwenden und ein konsistentes Ergebnis erwarten.
Ein bedeutender Vorteil von POST ist, dass es Entwicklern ermöglicht, Ressourcen explizit zu definieren. Diese Funktion verhindert, dass Teams versehentlich untergeordnete Ressourcen erstellen, die den Code verunreinigen, die Referenzen verwirren und zu Problemen in den Anwendungen führen.
Methode 2: PUT
Das Äquivalent von POST für eine einzelne Ressource ist PUT, mit dem eine Ressource aktualisiert wird, indem ihr Inhalt vollständig ersetzt wird. Als RESTful-API-HTTP-Methode ist PUT die gängigste Methode zur Aktualisierung von Ressourceninformationen.
Es ist möglich, eine Ressource mit einer PUT-Methode zu erstellen, aber dieser Ansatz birgt das Risiko, Ressourcen versehentlich zu erstellen, wie oben erwähnt. Wenn PUT auf eine Ressourcensammlung angewendet wird, wird die gesamte Ressourcensammlung ersetzt, was normalerweise nicht beabsichtigt ist.
Methode 3: PATCH
PATCH ist eine weitere HTTP-Methode, die zur Aktualisierung von Ressourcen verwendet wird. Im Gegensatz zum Ersetzen von Ressourcen, wie es die PUT-Methode tut, ändert PATCH nur den Inhalt von Ressourcen. In der Regel sollten diese Änderungen in einem Standardformat wie JSON oder XML ausgedrückt werden.
Ähnlich wie bei PUT ist es keine gute Praxis, PATCH-Methoden speziell auf eine ganze Ressourcensammlung anzuwenden – es sei denn, Sie beabsichtigen wirklich, jede darin enthaltene Ressource zu aktualisieren.
Ein Hinweis zur Methodendokumentation
Alle HTTP-Methoden liefern einen Rückgabewert und können auch Daten zurückgeben. Es liegt in der Verantwortung der Ressourcensoftware, korrekte Rückgabecodes zu erzeugen, und die Beziehung zwischen Methoden, Ressourcenzuständen und Rückgabecodes muss für den Client dokumentiert werden.
Wenn Sie sich nicht an die Standardkonventionen für Rückgabecodes halten wollen, müssen Sie diese Entscheidung klar dokumentieren und die von Ihnen verwendeten benutzerdefinierten Codes explizit aufführen. Andernfalls werden Sie nur diejenigen verwirren, die die Anwendungen später warten müssen – und die wahrscheinlich noch nicht da waren, als Sie Ihr eigenes Rückgabesystem erfunden haben.
Methode 4: GET
Die gängigste HTTP-Methode ist GET, die eine repräsentative Ansicht der Inhalte und Daten einer Ressource zurückgibt. GET sollte im Nur-Lese-Modus verwendet werden, damit die Daten sicher und die Ressource idempotent sind. Sie sollten immer die gleichen Ergebnisse erhalten, egal wie oft Sie diese Methode verwenden, es sei denn, sie wurde in der Zwischenzeit von einem anderen Client geändert.
Die GET-Methode wird manchmal verwendet, um den Inhalt einer Ressource zu ändern, aber das ist eine heikle Verwendung der Methode. Es ist üblich, die Fähigkeit eines Clients zum PATCH einer Ressource zu gefährden, wenn die Ressource eine Änderung feststellt, seit der PATCH-Client zuletzt einen GET durchgeführt hat.
Methode 5: DELETE
Die letzte zu untersuchende HTTP-Methode ist DELETE. Wenn eine DELETE-Methode auf eine einzelne Ressource abzielt, wird diese Ressource vollständig entfernt.
Die Implementierungen von DELETE sind in der Regel etwas uneinheitlich: Die URL für die Ressource kann verfügbar bleiben, auch wenn die eigentliche Ressource nicht mehr vorhanden ist. In einem solchen Szenario ist es möglich, dass der Server oder die Ressourcenimplementierung den Zustand der verschwundenen Ressource anhand der URL noch ändert und wahrscheinlich anders auf nachfolgende DELETE-Ausführungen reagiert.
Obwohl dies möglich ist, sollten Sie es generell vermeiden, die DELETE-Methode in einer Ressourcensammlung zu verwenden, da sie alle darin enthaltenen Inhalte löscht. Denken Sie daran, dass die Methode nicht idempotent ist und nicht als solche behandelt werden sollte.
