Jestem w trakcie projektowania interfejsu API HTTP, mam nadzieję, że uczynię go możliwie jak najbardziej REST.
Istnieje kilka działań, których funkcjonalność rozciąga się na kilka zasobów i czasem trzeba je cofnąć.
Pomyślałem sobie, że to brzmi jak wzorzec poleceń, ale jak mogę zamodelować go w zasób?
Przedstawię nowy zasób o nazwie XXAction, taki jak DepositAction, który zostanie utworzony poprzez coś takiego
POST /card/{card-id}/account/{account-id}/Deposit
AmountToDeposit=100, different parameters...
spowoduje to utworzenie nowej operacji DepositAction i aktywację jej metody Do / Execute. W takim przypadku zwrócenie statusu 201 Utworzono HTTP oznacza, że akcja została wykonana pomyślnie.
Później, jeśli klient chce przyjrzeć się szczegółom akcji, może
GET /action/{action-id}
Wydaje mi się, że aktualizacja / PUT powinna zostać zablokowana, ponieważ tutaj nie ma to znaczenia.
Aby cofnąć akcję, pomyślałem o użyciu
DELETE /action/{action-id}
który faktycznie wywoła metodę Cofnij odpowiedniego obiektu i zmieni jego status.
Powiedzmy, że jestem zadowolony z tylko jednego cofania, nie muszę tego robić ponownie.
Czy to podejście jest w porządku?
Czy są jakieś pułapki, powody, aby z niego nie korzystać?
Czy to rozumie się z POV klientów?
źródło
Odpowiedzi:
Dodajesz warstwę abstrakcji, która jest myląca
Twój interfejs API zaczyna się bardzo czysty i prosty. HTTP POST tworzy nowy zasób depozytowy z podanymi parametrami. Następnie zejdziesz z torów, wprowadzając ideę „działań”, które są szczegółami implementacyjnymi, a nie podstawową częścią interfejsu API.
Alternatywnie rozważ tę rozmowę HTTP ...
Teraz chcesz cofnąć tę operację (technicznie nie powinno to być dozwolone w zrównoważonym systemie księgowym, ale hej):
Klient interfejsu API wie, że ma do czynienia z zasobem depozytowym i jest w stanie określić, jakie operacje są na nim dozwolone (zwykle poprzez OPCJE w HTTP).
Chociaż wdrożenie operacji usuwania odbywa się dzisiaj za pomocą „akcji”, nie ma gwarancji, że migracja tego systemu z, powiedzmy, C # do Haskell i utrzymanie interfejsu użytkownika, że wtórna koncepcja „akcji” nadal będzie stanowić wartość dodaną , podczas gdy podstawowa koncepcja Depozytu na pewno działa.
Edytuj, aby objąć alternatywę dla USUŃ i Depozyt
Aby uniknąć operacji usuwania, ale nadal skutecznie usuwać Depozyt, wykonaj następujące czynności (używając ogólnej Transakcji, aby umożliwić Depozyt i Wypłatę):
Tworzony jest nowy zasób transakcji, który ma dokładnie przeciwną kwotę (-100). Powoduje to równoważenie konta z powrotem do 0, co neguje pierwotną transakcję.
Możesz rozważyć utworzenie punktu końcowego typu „narzędzie”
aby uzyskać ten sam efekt. Jednak łamie to semantykę identyfikatora URI jako identyfikatora poprzez wprowadzenie czasownika. Lepiej trzymaj się rzeczowników w identyfikatorach i ograniczaj operacje do czasowników HTTP. W ten sposób możesz łatwo utworzyć permalink z identyfikatora i używać go do GET i tak dalej.
źródło
Głównym powodem istnienia REST jest odporność na błędy sieciowe. W tym celu wszystkie operacje powinny być idempotentne .
Podstawowe podejście wydaje się rozsądne, ale sposób, w jaki opisujesz
DepositActionstworzenie, nie wydaje się idempotentny, co powinno zostać naprawione. Klient musi podać unikalny identyfikator, który będzie używany do wykrywania duplikatów żądań. Tak więc stworzenie zmieni się naJeśli zostanie wykonane inne PUT dla tego samego adresu URL z taką samą treścią jak poprzednio, odpowiedź powinna nadal brzmieć,
201 createdjeśli treść jest taka sama, i błąd, jeśli treść jest inna. Dzięki temu klient może po prostu retransmitować żądanie, gdy się nie powiedzie, ponieważ klient nie może stwierdzić, czy żądanie lub odpowiedź zaginęły.Bardziej sensowne jest użycie PUT, ponieważ po prostu zapisuje zasób i jest idempotentny, ale użycie POST tak naprawdę nie spowoduje żadnego problemu.
Aby zobaczyć szczegóły transakcji, klient będzie miał
GETten sam adres URL, tji aby go cofnąć, można go usunąć. Ale jeśli faktycznie ma to coś wspólnego z pieniędzmi, jak sugeruje próbka, sugerowałbym PUT dodawanie flag „anulowanych” zamiast tego ze względu na odpowiedzialność (że pozostaje ślad utworzonej i anulowanej transakcji).
Teraz musisz wybrać metodę tworzenia unikalnego identyfikatora. Masz kilka opcji:
źródło