it-swarm.com.de

REST API PATCH oder PUT

Ich möchte meinen Ruheendpunkt mit der geeigneten Methode für das folgende Szenario entwerfen.

Es gibt eine Gruppe. Jede Gruppe hat einen Status. Die Gruppe kann vom Administrator aktiviert oder deaktiviert werden.

Soll ich meinen Endpunkt als gestalten 

PUT /groups/api/v1/groups/{group id}/status/activate

OR

PATCH /groups/api/v1/groups/{group id}

with request body like 
{action:activate|deactivate}
225
java_geek

Die PATCH-Methode ist hier die richtige Wahl, wenn Sie eine vorhandene Ressource - die Gruppen-ID - aktualisieren. PUT sollte nur verwendet werden, wenn Sie Ersetzen eine Ressource in ihrer Gesamtheit sind. 

Weitere Informationen zur teilweisen Ressourcenänderung finden Sie in RFC 5789 . Die PUT-Methode wird insbesondere wie folgt beschrieben:

Mehrere Anwendungen zur Erweiterung des Hypertext Transfer Protocol (HTTP) erfordert eine Funktion zur teilweisen Änderung der Ressource. Das Die vorhandene HTTP-PUT-Methode ermöglicht nur den vollständigen Ersatz einer dokumentieren. Dieser Vorschlag fügt die neue HTTP-Methode PATCH hinzu, um eine .__ zu ändern. vorhandene HTTP-Ressource.

276
Luke Peterson

Das R in REST steht für Ressource

(Was nicht stimmt, da es für Representational steht, aber es ist ein guter Trick, um sich an die Bedeutung von Ressourcen in REST zu erinnern.).

Über PUT /groups/api/v1/groups/{group id}/status/activate: Sie sind nicht, um ein "Aktivieren" zu aktualisieren. Ein "Aktivieren" ist keine Sache, es ist ein Verb. Verben sind niemals gute Ressourcen. Eine Faustregel: Wenn die Aktion, ein Verb, in der URL enthalten ist, ist es wahrscheinlich nicht RESTful .

Was machst du stattdessen? Entweder "hinzufügen", "entfernen" oder "aktualisieren" Sie eine Aktivierung in einer Gruppe, oder wenn Sie es vorziehen, eine "Status" -Ressource in einer Gruppe zu bearbeiten. Ich persönlich würde "Aktivierungen" verwenden, weil sie weniger eindeutig sind als das Konzept "Status": Das Erstellen eines Status ist mehrdeutig, das Erstellen einer Aktivierung nicht.

  • POST /groups/{group id}/activation Erzeugt eine Aktivierung (oder fordert deren Erstellung an).
  • PATCH /groups/{group id}/activation Aktualisiert einige Details einer vorhandenen Aktivierung. Da eine Gruppe nur eine Aktivierung hat, wissen wir, auf welche Aktivierungsressource wir uns beziehen.
  • PUT /groups/{group id}/activation Fügt die alte Aktivierung ein oder ersetzt diese. Da eine Gruppe nur eine Aktivierung hat, wissen wir, auf welche Aktivierungsressource wir uns beziehen.
  • DELETE /groups/{group id}/activation Bricht die Aktivierung ab oder entfernt sie.

Dieses Muster ist nützlich, wenn die "Aktivierung" einer Gruppe Nebeneffekte hat, z. B. Zahlungen, E-Mails usw. Nur POST und PATCH können solche Nebenwirkungen haben. Wenn z. Wenn Sie eine Aktivierung löschen, müssen Sie die Benutzer beispielsweise per E-Mail benachrichtigen. DELETE ist nicht die richtige Wahl. In diesem Fall möchten Sie wahrscheinlich eine Deaktivierungsressource erstellen: POST /groups/{group_id}/deactivation

Es ist eine gute Idee, diese Richtlinien zu befolgen, denn dieser Standardvertrag macht es für Ihre Kunden und alle Stellvertreter und Schichten zwischen dem Kunden und Ihnen sehr klar, wann es sicher ist, es erneut zu versuchen und wann nicht. Nehmen wir an, der Client befindet sich irgendwo mit flockigem WLAN, und sein Benutzer klickt auf "deactive", was eine DELETE auslöst: Wenn dies fehlschlägt, kann der Client es einfach wiederholen, bis er eine 404, 200 oder etwas anderes erhält. Wenn es jedoch einen POST to deactivation auslöst, kann er es nicht wiederholen: Der POST impliziert dies.
Jeder Client hat jetzt einen Vertrag, der, wenn er gefolgt wird, vor dem Versenden von 42 E-Mails schützt, "Ihre Gruppe wurde deaktiviert", einfach weil die HTTP-Bibliothek den Aufruf an das Backend wiederholt hat.

Aktualisieren eines einzelnen Attributs: Verwenden Sie PATCH

PATCH /groups/{group id}

Wenn Sie ein Attribut aktualisieren möchten. Z.B. Der "Status" kann ein Attribut für Gruppen sein, das festgelegt werden kann. Ein Attribut wie "Status" ist häufig ein guter Kandidat, um sich auf eine Whitelist von Werten zu beschränken. Beispiele verwenden ein undefiniertes JSON-Schema:

PATCH /groups/{group id} { "attributes": { "status": "active" } }
response: 200 OK

PATCH /groups/{group id} { "attributes": { "status": "deleted" } }
response: 406 Not Acceptable

Ersetzen der Ressource ohne Nebeneffekte mit PUT.

PUT /groups/{group id}

Wenn Sie eine ganze Gruppe ersetzen möchten. Dies bedeutet nicht notwendigerweise, dass der Server tatsächlich eine neue Gruppe erstellt und die alte Gruppe auswirft, z. Die IDs können gleich bleiben. Für die Clients bedeutet dies jedoch PUT can: Der Client sollte annehmen, dass er basierend auf der Antwort des Servers ein völlig neues Element erhält.

Der Client sollte im Fall einer PUT-Anforderung immer die gesamte Ressource mit allen Daten senden, die zum Erstellen eines neuen Elements erforderlich sind. In der Regel sind dieselben Daten erforderlich, die für ein POST-Erstellen erforderlich sind.

PUT /groups/{group id} { "attributes": { "status": "active" } }
response: 406 Not Acceptable

PUT /groups/{group id} { "attributes": { "name": .... etc. "status": "active" } }
response: 201 Created or 200 OK, depending on whether we made a new one.

Eine sehr wichtige Voraussetzung ist, dass PUT idempotent ist: Wenn Sie beim Aktualisieren einer Gruppe Nebeneffekte benötigen (oder eine Aktivierung ändern), sollten Sie PATCH verwenden. Wenn also die Aktualisierung z. Senden Sie eine E-Mail, verwenden Sie nicht PUT.

148
berkes

Ich würde die Verwendung von PATCH empfehlen, da Ihre Ressourcengruppe viele Eigenschaften hat. In diesem Fall aktualisieren Sie jedoch nur das Aktivierungsfeld (teilweise Änderung).

gemäß RFC5789 ( https://tools.ietf.org/html/rfc5789 )

Die vorhandene HTTP-Methode PUT erlaubt nur einen vollständigen Ersatz von ein Dokument. Dieser Vorschlag fügt die neue HTTP-Methode PATCH zum Ändern von .__ hinzu. eine vorhandene HTTP-Ressource.

Weitere Einzelheiten

Der Unterschied zwischen den PUT- und PATCH-Anforderungen spiegelt sich in der wie der Server die eingeschlossene Entität verarbeitet, um die Ressource zu ändern
identifiziert durch die Request-URI. In einer PUT-Anforderung die eingeschlossene Entität wird als modifizierte Version der Ressource betrachtet, die im gespeichert ist
Origin-Server, und der Client fordert die gespeicherte Version an
ersetzt werden. Bei PATCH enthält die eingeschlossene Entität jedoch eine Menge Anweisungen, in denen beschrieben wird, wie sich eine Ressource im Internet befindet
Der Origin-Server sollte geändert werden, um eine neue Version zu erstellen. Der PATCH Die Methode wirkt sich auf die Ressource aus, die durch den Request-URI identifiziert wurde
Kann auch Nebenwirkungen auf andere Ressourcen haben; neue Ressourcen
können erstellt oder bestehende durch die Anwendung eines modifiziert werden
PATCH.

PATCH ist weder sicher noch idempotent im Sinne von [RFC2616], Sektion 9.1.

Kunden müssen entscheiden, wann PATCH statt PUT verwendet wird. Zum
Beispiel, wenn die Größe des Patchdokuments größer ist als die Größe des
neue Ressourcendaten, die in einem PUT verwendet werden würden, könnten dann
Sinn, PUT anstelle von PATCH zu verwenden. Ein Vergleich mit POST ist noch mehr schwierig, weil POST auf sehr unterschiedliche Weise verwendet wird und kann
umfassen PUT- und PATCH-ähnliche Operationen, wenn der Server dies wählt. Ob
Die Operation ändert die von Request- .__ identifizierte Ressource nicht. URI auf vorhersagbare Weise POST sollte anstelle von PATCH betrachtet werden
oder PUT.

Der Antwortcode für PATCH lautet

Der Antwortcode 204 wird verwendet, weil die Antwort kein .__ enthält. Nachrichtentext (was eine Antwort mit dem 200-Code hätte). Hinweis dass andere Erfolgscodes ebenfalls verwendet werden könnten.

siehe auch thttp: //restcookbook.com/HTTP%20Methods/patch/

Vorbehalt: Eine API, die PATCH implementiert, muss einen atomaren Patch ausführen. Es darf nicht Möglicherweise sind die Ressourcen nur halb gepatcht, wenn sie von einem GET angefordert werden.

11

Da Sie eine API mit dem Architekturstil REST entwerfen möchten, müssen Sie über Ihre Anwendungsfälle nachdenken, um zu entscheiden, welche Konzepte wichtig genug sind, um sie als Ressourcen verfügbar zu machen. Wenn Sie sich entscheiden, den Status einer Gruppe als Unterressource bereitzustellen, können Sie ihr den folgenden URI zuweisen und die Unterstützung für GET- und PUT-Methoden implementieren: 

/groups/api/groups/{group id}/status

Der Nachteil dieses Ansatzes gegenüber PATCH besteht darin, dass Sie nicht mehr als eine Eigenschaft einer Gruppe atomar und transaktional ändern können. Wenn Transaktionsänderungen wichtig sind, verwenden Sie PATCH.

Wenn Sie sich entscheiden, den Status als Unterressource einer Gruppe anzuzeigen, sollte dies ein Link in der Darstellung der Gruppe sein. Wenn der Agent beispielsweise die Gruppe 123 erhält und XML akzeptiert, könnte der Antworttext Folgendes enthalten: 

<group id="123">
  <status>Active</status>
  <link rel="/linkrels/groups/status" uri="/groups/api/groups/123/status"/>
  ...
</group>

Ein Hyperlink ist erforderlich, um die Hypermedia als Engine des Status der Anwendung Bedingung des Architekturstils REST zu erfüllen.

7

Im Allgemeinen würde ich etwas einfacher bevorzugen, wie activate/deactivate Subressource (verknüpft durch einen Link-Header mit rel=service).

POST /groups/api/v1/groups/{group id}/activate

oder

POST /groups/api/v1/groups/{group id}/deactivate

Für den Konsumenten ist diese Schnittstelle ein Kinderspiel, und sie folgt REST Prinzipien, ohne Sie dabei zu behindern, "Aktivierungen" als individuelle Ressourcen zu konzipieren.

0
rich remer