Ich möchte meinen Ruheendpunkt mit der entsprechenden Methode für das folgende Szenario entwerfen.
Es gibt eine Gruppe. Jede Gruppe hat einen Status. Die Gruppe kann vom Administrator aktiviert oder inaktiviert werden.
Soll ich meinen Endpunkt als gestalten?
PUT /groups/api/v1/groups/{group id}/status/activate
ODER
PATCH /groups/api/v1/groups/{group id}
with request body like
{action:activate|deactivate}
http
rest
http-put
http-method
http-patch
java_geek
quelle
quelle
activate
" ist nicht ausreichend RESTful Konstruktion. Sie versuchen wahrscheinlich, dasstatus
auf "aktiv" oder "deaktivierend" zu aktualisieren . In diesem Fall können Sie.../status
mit der "aktiven" oder "deaktivierenden" Zeichenfolge im Körper PATCHEN. Oder wenn Sie versuchen, einen Booleschenstatus.active
Wert.../status/active
bei zu aktualisieren , können Sie mit dem Booleschen Wert im Körper PATCHENAntworten:
Die
PATCH
Methode ist hier die richtige Wahl, wenn Sie eine vorhandene Ressource aktualisieren - die Gruppen-ID.PUT
sollte nur verwendet werden, wenn Sie eine Ressource vollständig ersetzen .Weitere Informationen zur teilweisen Änderung von Ressourcen finden Sie in RFC 5789 . Insbesondere wird das
PUT
Verfahren wie folgt beschrieben:quelle
Das R in REST steht für Ressource
(Was nicht stimmt, weil es für Repräsentativ steht, aber es ist ein guter Trick, sich an die Bedeutung von Ressourcen in REST zu erinnern).
Über
PUT /groups/api/v1/groups/{group id}/status/activate
: Sie sind nicht ein „activate“ zu aktualisieren. Ein "Aktivieren" ist keine Sache, es ist ein Verb. Verben sind niemals gute Ressourcen. Eine Faustregel: Wenn sich die Aktion, ein Verb, in der URL befindet, ist sie wahrscheinlich nicht RESTful .Was machst du stattdessen? Entweder Sie "hinzufügen", "entfernen" oder "aktualisieren" eine Aktivierung für eine Gruppe, oder wenn Sie es vorziehen: Manipulieren einer "Status" -Ressource für eine Gruppe. Persönlich würde ich "Aktivierungen" verwenden, weil sie weniger mehrdeutig sind als das Konzept "Status": Das Erstellen eines Status ist mehrdeutig, das Erstellen einer Aktivierung nicht.
POST /groups/{group id}/activation
Erstellt 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 sie. 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 Nebenwirkungen hat, z. B. Zahlungen, gesendete E-Mails usw. Nur POST und PATCH können solche Nebenwirkungen haben. Wenn beispielsweise das Löschen einer Aktivierung beispielsweise Benutzer per E-Mail benachrichtigen muss, ist LÖSCHEN 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, da dieser Standardvertrag Ihren Kunden und allen Proxies und Schichten zwischen dem Kunden und Ihnen klar macht, wann ein erneuter Versuch sicher ist und wann nicht. Angenommen, der Client befindet sich irgendwo mit flockigem WLAN und sein Benutzer klickt auf "Deaktivieren", was Folgendes auslöst
DELETE
: Wenn dies fehlschlägt, kann der Client es einfach erneut versuchen, bis er eine 404, 200 oder etwas anderes erhält, das er verarbeiten kann. Wenn es jedoch a auslöstPOST to deactivation
, weiß es, dass es nicht erneut versucht werden muss: Der POST impliziert dies.Jeder Client hat jetzt einen Vertrag, der, wenn er befolgt wird, vor dem Versenden von 42 E-Mails schützt, "Ihre Gruppe wurde deaktiviert", einfach weil seine HTTP-Bibliothek den Anruf an das Backend wiederholt.
Aktualisieren eines einzelnen Attributs: Verwenden Sie PATCH
PATCH /groups/{group id}
Falls Sie ein Attribut aktualisieren möchten. Beispielsweise könnte der "Status" ein Attribut für Gruppen sein, das festgelegt werden kann. Ein Attribut wie "Status" ist oft ein guter Kandidat, um sich auf eine Whitelist von Werten zu beschränken. Beispiele verwenden ein undefiniertes JSON-Schema:
Ersetzen Sie die Ressource ohne Nebenwirkungen und verwenden Sie PUT.
PUT /groups/{group id}
Falls Sie eine ganze Gruppe ersetzen möchten. Dies bedeutet nicht unbedingt, dass der Server tatsächlich eine neue Gruppe erstellt und die alte Gruppe herauswirft, z. B. können die IDs gleich bleiben. Für die Clients kann PUT jedoch Folgendes bedeuten: Der Client sollte davon ausgehen, dass er basierend auf der Antwort des Servers ein völlig neues Element erhält.
Der Client sollte im Falle einer
PUT
Anforderung immer die gesamte Ressource senden und über alle Daten verfügen, die zum Erstellen eines neuen Elements erforderlich sind. In der Regel sind dieselben Daten erforderlich, die für eine POST-Erstellung erforderlich sind.Eine sehr wichtige Anforderung ist, dass sie
PUT
idempotent ist: Wenn Sie beim Aktualisieren einer Gruppe (oder beim Ändern einer Aktivierung) Nebenwirkungen benötigen, sollten Sie diese verwendenPATCH
. Wenn das Update beispielsweise zum Versenden einer E-Mail führt, verwenden Sie es nichtPUT
.quelle
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 )
Auch in weiteren Details,
Der Antwortcode für PATCH lautet
Siehe auch thttp: //restcookbook.com/HTTP%20Methods/patch/
quelle
Da Sie eine API im REST-Architekturstil entwerfen möchten, müssen Sie über Ihre Anwendungsfälle nachdenken, um zu entscheiden, welche Konzepte wichtig genug sind, um als Ressourcen verfügbar gemacht zu werden. Wenn Sie den Status einer Gruppe als Unterressource verfügbar machen möchten, können Sie ihr den folgenden URI geben und die Unterstützung für GET- und PUT-Methoden implementieren:
Der Nachteil dieses Ansatzes gegenüber PATCH zur Änderung besteht darin, dass Sie nicht in der Lage sind, Änderungen an mehr als einer Eigenschaft einer Gruppe atomar und transaktional vorzunehmen. Wenn Transaktionsänderungen wichtig sind, verwenden Sie PATCH.
Wenn Sie den Status als Unterressource einer Gruppe verfügbar machen möchten, sollte dies ein Link in der Darstellung der Gruppe sein. Wenn der Agent beispielsweise die Gruppe 123 erhält und XML akzeptiert, kann der Antworttext Folgendes enthalten:
Ein Hyperlink wird benötigt, um die Hypermedien als Engine für die Anwendungsstatusbedingung des REST-Architekturstils zu erfüllen .
quelle
Ich würde im Allgemeinen etwas Einfacheres bevorzugen, wie
activate
/deactivate
sub-resource (verbunden durch einenLink
Header mitrel=service
).oder
Für den Verbraucher ist diese Schnittstelle kinderleicht und folgt den REST-Prinzipien, ohne Sie bei der Konzeption von "Aktivierungen" als einzelne Ressourcen zu stören.
quelle
Eine mögliche Option zur Implementierung eines solchen Verhaltens ist
Und wenn jemand es deaktivieren muss,
PUT
hat es natürlich denDeactivated
Status in JSON.Im Falle der Notwendigkeit einer Massenaktivierung / -deaktivierung
PATCH
kann das Spiel betreten werden (nicht für die genaue Gruppe, sondern für diegroups
Ressource:Im Allgemeinen ist dies eine Idee, wie @Andrew Dobrowolski vorschlägt, jedoch mit geringfügigen Änderungen in der genauen Realisierung.
quelle