Punkt końcowy REST, aby wyświetlić podgląd przed testem POST

Projektuję nową aplikację internetową, która jest oparta na zapleczu REST i nakładce HTML + JS.

Jest na nim jedna metoda POST , aby zmienić jeden byt (nazwijmy Config), który ma kilka skutków ubocznych w stanie wielu elementów aplikacji. Załóżmy, że test POST jest wykonywany w ten sposób:

POST /api/config BODY {config: ....}

Z tego powodu chciałbym wyświetlić podgląd przed wprowadzeniem tych zmian, aby użytkownik końcowy mógł zauważyć, co się zmieni.

Pierwszą rzeczą, o której pomyślałem, było utworzenie punktu końcowego GET dla podglądu, wysyłając treść nowego stanu encji. Tą drogą:

GET /api/preview/items BODY {config: ....}

Może pokazywać nowy stan elementów z nową konfiguracją.

GET /api/preview/sales BODY {config: ....}

Może pokazać nowy stan sprzedaży dzięki nowej konfiguracji.

Dobrym pomysłem wydaje się użycie czasownika GET, ponieważ nie zmieniam stanu aplikacji. Jednak stosowanie treści żądania z żądaniami GET wydaje się być odradzane .

Czy jest w tym jakaś dobra praktyka? Innym wyborem może być przechowywanie konfiguracji jako wersji roboczej za pomocą jednej metody i wyświetlanie wyników z innymi, ale wymagałoby to dodatkowego kroku i konieczności zarządzania wersjami roboczymi na serwerze:

POST /api/preview/config BODY {config: ....}

GET /api/preview/items?idPreviewConfig=1

Jest to zbyt specyficzne dla domeny, aby mieć macierzystą obsługę HTTP.

Zamiast tego możesz wykonać jedną z następujących czynności:

1. Mają POST /api/config/preview. Po stronie serwera aplikacja będzie wiedziała, że ​​nie powinna modyfikować faktycznej konfiguracji, ale połączyć rzeczywistą z opublikowaną i zwrócić wynik wskazujący, co zostało zmienione.

   Później, jeśli użytkownik będzie zadowolony z wyniku, wykona POST /api/configzawierający taki sam ładunek, jak w poprzednim żądaniu. Spowoduje to skuteczne zastąpienie konfiguracji.

   Zaletą tego podejścia jest to, że nie wprowadzasz żadnych przełomowych zmian w bieżącym interfejsie API. Klienci, którzy nie potrzebują funkcji podglądu, nadal będą mogli aktualizować wpisy, tak jak wcześniej.

   Wadą jest to, że gdy ciało jest duże, oznacza to, że konieczne będzie dwukrotne wysłanie go na serwer. Jeśli tak jest w twoim przypadku, możesz zastosować następne podejście.

2. Miej, POST /api/config/preparektóry pamięta, co zostało wysłane w tymczasowym rekordzie i zwraca dwie rzeczy: identyfikator rekordu tymczasowego (na przykład 12345) i podgląd zmian.

   Jeśli użytkownik jest zadowolony z wyniku, wykona a, POST /api/config/commit/12345aby ostatecznie zapisać zmiany. Jeśli nie, tymczasowy zapis może być przechowywany przez pewien czas, a następnie odrzucony przez zadanie cron.

   Zaletą jest to, że tutaj znowu możesz zachować POST /api/confignienaruszony oryginał , a klienci, którzy nie potrzebują podglądu, nie ulegną awarii.

   Wady polegają na tym, że (1) obsługa usuwania tymczasowych rekordów może być trudna (co sprawia, że ​​myślisz, że jedna godzina wystarczy? Co jeśli dziesięć minut później zabraknie pamięci? Jak klienci obsługują HTTP 404 podczas wykonywania zatwierdzenia rekord, który wygasł?) i że (2) dwuetapowe przesłanie rekordu może być bardziej skomplikowane, niż to konieczne.

3. Przenieś logikę podglądu po stronie klienta.

Używanie określonych czasowników HTTP do różnych wywołań API w REST polega na wykorzystaniu istniejącej mechaniki i oczekiwań HTTP.

Użycie GET w tym przypadku wydaje się być sprzeczne z obiema.

A. Klient musi dołączyć ciało z GET? niespodziewany

B. Serwer zwraca inną odpowiedź na get w zależności od treści? łamie specyfikację i mechanizmy buforowania

Jeśli zmagasz się z ODPOWIEDNIMI pytaniami, moją zasadą jest zadać sobie pytanie.

„Jak to jest lepsze niż używanie POST do wszystkiego?”

O ile nie ma natychmiastowej i oczywistej korzyści, wybierz strategię Just Use POST Stupid (JUPS)

Możesz wysłać nagłówek, który wskazuje serwerowi: „nie utrzymuj tego, pokaż mi tylko, jaki byłby wynik, gdybyś to zrobił”. Na przykład

POST /api/config HTTP/1.1
Host: api.mysite.com
Content-Type: application/json
Persistence-Options: simulate

{
   "config": {
      "key": "value"
   }
}

Na który serwer może odpowiedzieć:

HTTP/1.1 200 OK
Persistence-Options: simulated
Content-Type: application/json

-- preview --

Pamiętaj, że jeśli korzystasz z DB w oparciu o transakcje O / RM i / lub transakcje na żądanie, możesz łatwo wdrożyć tę funkcjonalność dla wszystkich swoich punktów końcowych, nie wymagając pracy na żadnym konkretnym punkcie końcowym: Jeśli żądanie przychodzi z tą opcją , wycofaj transakcję / jednostkę pracy zamiast ją zatwierdzać.

Proponuję potraktować to tak samo, jak traktujesz wyszukiwania. Ustawiłbym punkt końcowy POST, w /api/config/previewktórym TWORZY nowy podgląd. Następnie ustawiłbym punkt końcowy PUT lub PATCH w api/configzależności od tego, czy zamierzasz edytować bieżącą konfigurację, czy po prostu zastąpić całą konfigurację (przypuszczalnie w pierwszym przypadku wysyłałeś właśnie utworzony podgląd).

Oprócz innych dobrych odpowiedzi, inną opcją może być opublikowanie konfiguracji, jak wspomniano, i mieć również dostęp do procesu wycofywania. Myślę, że podobnie jak metodologia Agile, lepiej być mniej wystraszonym zmianami dzięki bardziej szczegółowym, powtarzalnym i przetestowanym procedurom, a to dałoby ci kopię zapasową, gdy jej potrzebujesz, zmniejszając ryzyko do niewielkiego lub żadnego, zależnie od aplikacji .

Z drugiej strony, jeśli możesz mieć błędy konfiguracji wpływające na cały system, chciałbyś obsłużyć go bardziej aktywnie, a jeśli tak, to dlaczego nie po prostu włożyć wysiłku w podgląd zmian w tym momencie, z perspektywy serwera lub klienta. Chociaż widzę, jak ta funkcja podglądu może być droższa w opracowaniu, przypadki użycia mają własny zestaw różnych kroków do wykonania i przetestowania.

RFC6648 zastępuje nowe X-konstrukcje, więc muszę głosować przeciwko pomysłowi wysłania nowego pola nagłówka. REST to styl architektury, o którym mówimy, jest RESTful - ale na razie zignorujmy to.

Ponieważ REST jest reprezentatywny (a symulacja nie ma reprezentacji w rzeczywistości) i stanowy (a symulacja nie jest stanem do czasu jego zatwierdzenia), musimy mieć nowy zakres, na przykład zakres symulacji. Ale musimy to nazwać emulacją zamiast symulacji, ponieważ symulacja obejmuje proces symulacji, ale stanowy oznacza, że ​​mamy stan stały, idealne rozwiązanie symulacji: emulacja. Musimy więc nazwać to emulacją w adresie URL. To może być również dobre rozwiązanie:

GET  /api/emulation - 200 OK {first:1, last:123}
POST /api/emulation/124 - 200 OK
GET  /api/emulation/124/config - 200 OK {config:{tax:8}}
PUT  /api/emulation/124/config {config:{tax:16}} - 200 OK {config:{tax:16}}
GET  /api/emulation/124/items - 200 OK [first:1, last: 3000]
GET  /api/emulation/124/items/1 - 200 OK {price:1.79, name:'Cup'}
--- show emulation ---
--- commit emulation ---
PUT /api/config {config:{tax:16}}
DELETE /api/emulation/124 - 200 OK

Istnieje inne podejście ... możesz zauważyć, że wiele żądań z klienta HTML / JavaScript może wygenerować zbyt wiele żądań , co osiąga limit około 17 żądań jednocześnie (spójrz na tę stronę ). Możesz zamienić użycie REST i zamiast dostarczać słabe stany obiektowe, możesz dostarczać bogate stany stron specyficzne dla użytkownika. Przykład:

GET /user/123/config - 200 OK {user:'Tim', date:3298347239847, currentItem:123, 
                  roles:['Admin','Customer'], config:{tax:16}, unsavedChanges:true, ...}

Z poważaniem