Chcę zaprojektować mój punkt końcowy odpoczynku przy użyciu odpowiedniej metody dla następującego scenariusza.
Jest grupa. Każda grupa ma status. Grupa może być aktywowana lub dezaktywowana przez administratora.
Czy powinienem zaprojektować mój punkt końcowy jako
PUT /groups/api/v1/groups/{group id}/status/activate
LUB
PATCH /groups/api/v1/groups/{group id}
with request body like
{action:activate|deactivate}
http
rest
http-put
http-method
http-patch
java_geek
źródło
źródło
activate
” nie jest odpowiednią konstrukcją RESTful. Prawdopodobnie próbujesz zaktualizowaćstatus
opcję „aktywne” lub „nieaktywne”. w takim przypadku możesz PATCHOWAĆ.../status
z ciągiem „aktywnym” lub „dezaktywującym” w ciele. Lub jeśli próbujesz zaktualizować wartość logiczną ostatus.active
, możesz PATCHOWAĆ.../status/active
z wartością logiczną w cieleOdpowiedzi:
PATCH
Metoda jest poprawny wybór tu jesteś aktualizowania istniejącego zasobu - identyfikator grupy.PUT
powinien być używany tylko wtedy, gdy wymieniasz zasób w całości.Dalsze informacje na temat częściowej modyfikacji zasobów są dostępne w RFC 5789 . W szczególności
PUT
metodę opisano w następujący sposób:źródło
R w REST oznacza zasób
(Co nie jest prawdą, ponieważ oznacza Reprezentację, ale dobrym pomysłem jest zapamiętanie znaczenia zasobów w REST).
Informacje
PUT /groups/api/v1/groups/{group id}/status/activate
: nie aktualizujesz „aktywuj”. „Aktywacja” nie jest rzeczą, to czasownik. Czasowniki nigdy nie są dobrymi zasobami. Ogólna zasada: jeśli akcja, czasownik, znajduje się w adresie URL, prawdopodobnie nie jest to RESTful .Co zamiast tego robisz? Albo „dodajesz”, „usuwasz” lub „aktualizujesz” aktywację w grupie, albo jeśli wolisz: manipulujesz zasobem „statusowym” w grupie. Osobiście użyłbym „aktywacji”, ponieważ są one mniej dwuznaczne niż pojęcie „status”: tworzenie statusu jest niejednoznaczne, tworzenie aktywacji nie jest.
POST /groups/{group id}/activation
Tworzy (lub prosi o utworzenie) aktywacji.PATCH /groups/{group id}/activation
Aktualizuje niektóre szczegóły istniejącej aktywacji. Ponieważ grupa ma tylko jedną aktywację, wiemy, do jakiego zasobu aktywacyjnego mamy na myśli.PUT /groups/{group id}/activation
Wstawia lub zastępuje starą aktywację. Ponieważ grupa ma tylko jedną aktywację, wiemy, do jakiego zasobu aktywacyjnego mamy na myśli.DELETE /groups/{group id}/activation
Anuluje lub usunie aktywację.Ten wzór jest przydatny, gdy „aktywacja” grupy ma skutki uboczne, takie jak dokonywanie płatności, wysyłanie wiadomości e-mail i tak dalej. Tylko POST i PATCH mogą mieć takie skutki uboczne. Gdy np. Usunięcie aktywacji wymaga, powiedzmy, powiadomienia użytkowników pocztą, DELETE nie jest właściwym wyborem; w takim przypadku prawdopodobnie chcesz utworzyć zasób dezaktywacji :
POST /groups/{group_id}/deactivation
.Dobrym pomysłem jest przestrzeganie tych wytycznych, ponieważ ta standardowa umowa wyraźnie pokazuje klientom, a wszystkie proxy i warstwy między klientem a tobą wiedzą, kiedy można bezpiecznie ponowić próbę, a kiedy nie. Powiedzmy, że klient jest gdzieś z niestabilnym Wi-Fi, a jego użytkownik klika „dezaktywuj”, co powoduje
DELETE
: Jeśli to się nie powiedzie, klient może po prostu spróbować ponownie, aż otrzyma 404, 200 lub cokolwiek innego, co może obsłużyć. Ale jeśli uruchomi sięPOST to deactivation
, wie, że nie można ponowić: POST implikuje to.Każdy klient ma teraz umowę, której przestrzeganie ochroni przed wysłaniem 42 e-maili „Twoja grupa została zdezaktywowana”, po prostu dlatego, że jej biblioteka HTTP ponawiała połączenie z backendem.
Aktualizowanie pojedynczego atrybutu: użyj PATCH
PATCH /groups/{group id}
W przypadku, gdy chcesz zaktualizować atrybut. Np. „Status” może być atrybutem w Grupach, które można ustawić. Atrybut taki jak „status” jest często dobrym kandydatem do ograniczenia do białej listy wartości. Przykłady wykorzystują niezdefiniowany schemat JSON:
Zastępując zasób bez efektów ubocznych użyj PUT.
PUT /groups/{group id}
Jeśli chcesz zastąpić całą Grupę. Nie musi to koniecznie oznaczać, że serwer faktycznie tworzy nową grupę i wyrzuca starą, np. Identyfikatory mogą pozostać takie same. Ale dla klientów to właśnie może oznaczać PUT : klient powinien założyć, że otrzymuje zupełnie nowy przedmiot, w oparciu o odpowiedź serwera.
W przypadku
PUT
żądania klient powinien zawsze wysyłać cały zasób, mając wszystkie dane potrzebne do utworzenia nowego elementu: zwykle te same dane, których wymagałoby utworzenie POST.Bardzo ważnym wymogiem jest
PUT
idempotent: jeśli potrzebujesz efektów ubocznych podczas aktualizacji Grupy (lub zmiany aktywacji), powinieneś użyćPATCH
. Jeśli więc aktualizacja spowoduje np. Wysłanie wiadomości e-mail, nie należy jej używaćPUT
.źródło
Polecam użycie PATCH, ponieważ twoja grupa zasobów ma wiele właściwości, ale w tym przypadku aktualizujesz tylko pole aktywacji (częściowa modyfikacja)
zgodnie z RFC5789 ( https://tools.ietf.org/html/rfc5789 )
Ponadto, bardziej szczegółowo
Kod odpowiedzi dla PATCH to
patrz również: http: //restcookbook.com/HTTP%20Methods/patch/
źródło
Ponieważ chcesz zaprojektować interfejs API przy użyciu stylu architektonicznego REST, musisz pomyśleć o swoich przypadkach użycia, aby zdecydować, które koncepcje są wystarczająco ważne, aby ujawnić je jako zasoby. Jeśli zdecydujesz się na ujawnienie statusu grupy jako zasobu podrzędnego, możesz podać jej następujący identyfikator URI i zaimplementować obsługę metod GET i PUT:
Wadą tego podejścia w stosunku do PATCH w zakresie modyfikacji jest to, że nie będziesz w stanie dokonywać zmian w więcej niż jednej właściwości grupy atomowo i transakcyjnie. Jeśli zmiany transakcyjne są ważne, użyj PATCH.
Jeśli zdecydujesz się ujawnić status jako podrzędny zasób grupy, powinien to być link w reprezentacji grupy. Na przykład, jeśli agent pobierze grupę 123 i zaakceptuje XML, treść odpowiedzi może zawierać:
Hiperlink jest potrzebny do spełnienia hipermediów jako silnika stanu stanu aplikacji stylu architektonicznego REST.
źródło
Generalnie wolałbym coś nieco prostszego, na przykład
activate
/deactivate
sub-resource (połączoneLink
nagłówkiem zrel=service
).lub
Dla konsumenta ten interfejs jest niesamowicie prosty i działa zgodnie z zasadami REST, nie wprowadzając cię w konceptualizację „aktywacji” jako pojedynczych zasobów.
źródło
Jedną z możliwych opcji wdrożenia takiego zachowania jest
I oczywiście, jeśli ktoś będzie musiał go dezaktywować,
PUT
będzie miałDeactivated
status w JSON.W przypadku konieczności masowej aktywacji / dezaktywacji
PATCH
może wejść do gry (nie dla dokładnej grupy, ale dlagroups
zasobu:Ogólnie jest to pomysł, jak sugeruje @Andrew Dobrowolski, ale z niewielkimi zmianami w dokładnej realizacji.
źródło