REST-APIs ermöglichen es Ihnen, jede Art von Webanwendung mit allen möglichen CRUD-Operationen (Erstellen, Abrufen, Aktualisieren, Löschen) zu entwickeln. Die REST-Richtlinien empfehlen die Verwendung einer bestimmten HTTP-Methode für eine bestimmte Art von Aufrufen an den Server (obwohl es technisch möglich ist, diese Richtlinie zu verletzen, wird davon jedoch dringend abgeraten).
Nutzen Sie die nachstehenden Informationen, um eine geeignete HTTP-Methode für die von der API durchgeführte Aktion zu finden.
Table of ContentsHTTP GETHTTP POSTHTTP PUTHTTP DELETEHTTP PATCHSummaryGlossary
HTTP GET
Verwenden Sie GET-Anfragen nur zum Abrufen von Ressourcendarstellungen/Informationen – und nicht, um sie in irgendeiner Weise zu ändern. Da GET-Anfragen den Zustand der Ressource nicht verändern, gelten sie als sichere Methoden. Außerdem sollten GET-APIs idempotent sein, was bedeutet, dass mehrere identische Anfragen jedes Mal das gleiche Ergebnis liefern müssen, bis eine andere API (POST oder PUT) den Zustand der Ressource auf dem Server geändert hat.
Wenn die Request-URI auf einen datenproduzierenden Prozess verweist, sind es die produzierten Daten, die als Entität in der Antwort zurückgegeben werden, und nicht der Quelltext des Prozesses, es sei denn, dieser Text ist die Ausgabe des Prozesses.
Für jede gegebene HTTP GET API, wenn die Ressource auf dem Server gefunden wird, dann muss sie den HTTP Response Code 200 (OK) zurückgeben – zusammen mit dem Response Body, der normalerweise entweder XML oder JSON Inhalt ist (aufgrund ihrer plattformunabhängigen Natur).
Falls die Ressource NICHT auf dem Server gefunden wird, dann muss sie den HTTP Response Code 404 (NOT FOUND) zurückgeben. Ähnlich, wenn festgestellt wird, dass die GET-Anfrage selbst nicht korrekt geformt ist, dann wird der Server den HTTP-Antwortcode 400 (BAD REQUEST) zurückgeben.
Beispiel für Anfrage-URIs
- HTTP GET http://www.appdomain.com/users
- HTTP GET http://www.appdomain.com/users?size=20&page=5
- HTTP GET http://www.appdomain.com/users/123
- HTTP GET http://www.appdomain.com/users/123/address
HTTP POST
Benutzen Sie POST APIs um neue untergeordnete Ressourcen zu erstellen, z.B., eine Datei ist einem Verzeichnis untergeordnet, das sie enthält, oder eine Zeile ist einer Datenbanktabelle untergeordnet. Wenn man strikt von REST spricht, werden POST-Methoden verwendet, um eine neue Ressource in der Ressourcensammlung zu erstellen.
In der Regel, wenn eine Ressource auf dem Ursprungsserver erstellt wurde, SOLLTE die Antwort den HTTP-Antwortcode 201 (Created) haben und eine Entität enthalten, die den Status der Anfrage beschreibt und auf die neue Ressource verweist, sowie einen Location-Header.
In vielen Fällen kann die von der POST-Methode durchgeführte Aktion nicht zu einer Ressource führen, die durch einen URI identifiziert werden kann. In diesem Fall ist entweder der HTTP-Antwortcode 200 (OK) oder 204 (No Content) der geeignete Antwortstatus.
Antworten auf diese Methode sind nicht cachefähig, es sei denn, die Antwort enthält entsprechende Cache-Control- oder Expires-Header-Felder.
Bitte beachten Sie, dass POST weder sicher noch idempotent ist und der Aufruf zweier identischer POST-Anfragen zu zwei verschiedenen Ressourcen führt, die dieselben Informationen enthalten (mit Ausnahme der Ressourcen-IDs).
Beispielanforderungs-URIs
- HTTP POST http://www.appdomain.com/users
- HTTP POST http://www.appdomain.com/users/123/accounts
HTTP PUT
Verwenden Sie PUT-APIs in erster Linie, um bestehende Ressourcen zu aktualisieren (wenn die Ressource nicht existiert, kann die API entscheiden, ob eine neue Ressource erstellt wird oder nicht). Wenn eine neue Ressource durch die PUT-API erstellt wurde, MUSS der Ursprungsserver den Benutzeragenten über den HTTP-Antwortcode 201 (Created) informieren, und wenn eine vorhandene Ressource geändert wird, SOLLTE entweder der Antwortcode 200 (OK) oder 204 (No Content) gesendet werden, um den erfolgreichen Abschluss der Anfrage anzuzeigen.
Wenn die Anfrage einen Cache durchläuft und die Request-URI eine oder mehrere aktuell zwischengespeicherte Entitäten identifiziert, SOLLTEN diese Einträge als veraltet behandelt werden. Antworten auf diese Methode sind nicht cachefähig.
Beispiel für Request-URIs
- HTTP PUT http://www.appdomain.com/users/123
- HTTP PUT http://www.appdomain.com/users/123/accounts/456
HTTP DELETE
Wie der Name schon sagt, werden DELETE-APIs zum Löschen von Ressourcen (identifiziert durch die Request-URI) verwendet.
Eine erfolgreiche Antwort auf DELETE-Anfragen SOLLTE HTTP-Response code 200 (OK) sein, wenn die Antwort eine Entität enthält, die den Status beschreibt, 202 (Accepted), wenn die Aktion in die Warteschlange gestellt wurde, oder 204 (No Content), wenn die Aktion ausgeführt wurde, die Antwort aber keine Entität enthält.
DELETE-Operationen sind idempotent. Wenn Sie eine Ressource LÖSCHEN, wird sie aus der Sammlung von Ressourcen entfernt. Ein wiederholter Aufruf der DELETE-API für diese Ressource wird das Ergebnis nicht ändern – ein zweiter Aufruf von DELETE für eine Ressource wird jedoch eine 404 (NOT FOUND) zurückgeben, da sie bereits entfernt wurde. Einige mögen argumentieren, dass die DELETE-Methode dadurch nicht mehr identisch ist. Es ist eine Frage der Diskussion und der persönlichen Meinung.
Wenn die Anfrage einen Cache durchläuft und die Request-URI eine oder mehrere aktuell gecachte Entitäten identifiziert, SOLLTEN diese Einträge als veraltet behandelt werden. Antworten auf diese Methode sind nicht cachefähig.
Beispielanforderungs-URIs
- HTTP DELETE http://www.appdomain.com/users/123
- HTTP DELETE http://www.appdomain.com/users/123/accounts/456
HTTP PATCH
HTTP PATCH-Anforderungen dienen zur teilweisen Aktualisierung einer Ressource. Wenn Sie sehen, dass PUT-Anfragen auch eine Ressourcenentität ändern, ist die PATCH-Methode die richtige Wahl für die teilweise Aktualisierung einer bestehenden Ressource, und PUT sollte nur verwendet werden, wenn Sie eine Ressource in ihrer Gesamtheit ersetzen.
Bitte beachten Sie, dass es einige Herausforderungen gibt, wenn Sie sich entscheiden, PATCH-APIs in Ihrer Anwendung zu verwenden:
- Die Unterstützung für PATCH in Browsern, Servern und Webanwendungs-Frameworks ist nicht universell. IE8, PHP, Tomcat, Django und viele andere Software hat fehlende oder nicht funktionierende Unterstützung dafür.
- Die Nutzlast einer PATCH-Anfrage ist nicht so einfach wie bei einer PUT-Anfrage. z.B.
HTTP GET /users/1erzeugt folgende Antwort:
{id: 1, username: 'admin', email: ''}Ein Beispiel für eine Patch-Anfrage, um die E-Mail zu aktualisieren, sieht wie folgt aus:
HTTP PATCH /users/1“ }
]
Es gibt folgende mögliche Operationen gemäß der HTTP-Spezifikation.
},
{ "op": "replace", "path": "/a/b/c", "value": 42 },
{ "op": "move", "from": "/a/b/c", "path": "/a/b/d" },
{ "op": "copy","from": "/a/b/d", "path": "/a/b/e" }
]
Die PATCH-Methode ist kein Ersatz für die Methoden POST oder PUT. Sie wendet ein Delta (diff) an, anstatt die gesamte Ressource zu ersetzen.
Zusammenfassung der HTTP-Methoden für RESTful APIs
Die folgende Tabelle fasst die Verwendung der oben besprochenen HTTP-Methoden zusammen.
| HTTP-Methode | CRUD | Entire Collection (z.B.. /users) | Spezifisches Element (z.B. /users/123) |
|---|---|---|---|
| POST | Create | 201 (Created), ‚Location‘ Header mit Link zu /users/{id} mit neuer ID. | POST auf einzelne Ressource vermeiden |
| GET | Read | 200 (OK), Liste der Benutzer. Verwenden Sie Paginierung, Sortierung und Filterung, um in großen Listen zu navigieren. | 200 (OK), einzelner Benutzer. 404 (Not Found), wenn ID nicht gefunden oder ungültig. |
| PUT | Update/Replace | 405 (Methode nicht erlaubt), es sei denn, Sie wollen jede Ressource in der gesamten Ressourcensammlung aktualisieren. | 200 (OK) oder 204 (No Content). Verwenden Sie 404 (Not Found), wenn die ID nicht gefunden wurde oder ungültig ist. |
| PATCH | Partial Update/Modify | 405 (Methode nicht erlaubt), es sei denn, Sie wollen die Sammlung selbst ändern. | 200 (OK) oder 204 (Kein Inhalt). Verwenden Sie 404 (Not Found), wenn die ID nicht gefunden wurde oder ungültig ist. |
| DELETE | Delete | 405 (Methode nicht erlaubt), es sei denn, Sie wollen die gesamte Sammlung löschen – mit Vorsicht verwenden. | 200 (OK). 404 (Not Found), wenn die ID nicht gefunden wurde oder ungültig ist. |
Glossar
Sichere Methoden
Nach der HTTP-Spezifikation sollten die GET- und HEAD-Methoden nur zum Abrufen von Ressourcendarstellungen verwendet werden – und sie aktualisieren/löschen die Ressource auf dem Server nicht.
Dies ermöglicht es den Benutzeragenten, andere Methoden wie POST, PUT und DELETE in einer eindeutigen Weise darzustellen, so dass der Benutzer auf die Tatsache aufmerksam gemacht wird, dass eine möglicherweise unsichere Aktion angefordert wird – und sie können die Ressource auf dem Server aktualisieren/löschen und sollten daher vorsichtig verwendet werden.
Idempotente Methoden
Der Begriff idempotent wird umfassender verwendet, um eine Operation zu beschreiben, die bei einmaliger oder mehrfacher Ausführung die gleichen Ergebnisse liefert. Idempotenz ist in vielen Situationen eine praktische Eigenschaft, da sie bedeutet, dass eine Operation so oft wie nötig wiederholt werden kann, ohne unbeabsichtigte Auswirkungen zu verursachen. Bei nicht-idempotenten Operationen muss der Algorithmus unter Umständen verfolgen, ob die Operation bereits ausgeführt wurde oder nicht.
In der HTTP-Spezifikation sind die Methoden GET, HEAD, PUT und DELETE als idempotente Methoden deklariert. Andere Methoden OPTIONS und TRACE SOLLTEN KEINE Seiteneffekte haben, also sind beide auch von Natur aus idempotent.