Implementowanie wzorca poleceń w interfejsie API RESTful

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?

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 ...

POST / card / {card-id} / account / {account-id} / Depozyt

AmountToDeposit = 100, różne parametry ...

201 STWORZONY

Lokalizacja = / karta / 123 / konto / 456 / Depozyt / 789

Teraz chcesz cofnąć tę operację (technicznie nie powinno to być dozwolone w zrównoważonym systemie księgowym, ale hej):

USUŃ / karta / 123 / konto / 456 / Depozyt / 789

204 BRAK TREŚCI

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ę):

POST / card / {card-id} / account / {account-id} / Transaction

Kwota = -100 , różne parametry ...

201 STWORZONY

Lokalizacja = / karta / 123 / konto / 456 / Transacja / 790

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”

POST / card / {card-id} / account / {account-id} / Transaction / 789 / Undo <- BAD!

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.

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ę na

PUT /card/{card-id}/account/{account-id}/Deposit/{action-id}
AmountToDeposit=100, different parameters...

Jeś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, tj

GET /card/{card-id}/account/{account-id}/Deposit/{action-id}

i 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:

1. Wydawaj wcześniej w wymianie specyficzny dla klienta prefiks, który należy uwzględnić.
2. Dodaj specjalne żądanie POST, aby uzyskać pusty unikalny identyfikator z serwera. To żądanie nie musi być idempotentne (i nie może tak naprawdę), ponieważ nieużywane identyfikatory nie powodują żadnych problemów.
3. Po prostu użyj UUID. Wszyscy ich używają i wydaje się, że nikt nie ma problemu z tymi opartymi na MACie ani z przypadkowymi.