Manipulacja zbiorową kolekcją za pomocą REST (RESTful) API

Question

Chciałbym uzyskać porady dotyczące projektowania interfejsu API REST, który umożliwi klientom efektywne dodawanie/usuwanie dużej liczby obiektów do kolekcji.

Za pośrednictwem interfejsu API klienci muszą mieć możliwość dodawania elementów do kolekcji i usuwania z niej elementów, a także manipulowania istniejącymi elementami. W wielu przypadkach klient będzie chciał dokonać zbiorczej aktualizacji kolekcji, np. dodając 1000 pozycji i usuwając 500 różnych przedmiotów. Wydaje się, że klient powinien móc to zrobić w pojedynczej transakcji z serwerem, zamiast wymagać 1000 oddzielnych żądań POST i 500 DELETE.

Czy ktoś ma jakieś informacje o najlepszych praktykach lub konwencjach do osiągnięcia tego?

Moje obecne myślenie jest takie, że powinno być możliwe naniesienie obiektu reprezentującego zmianę do identyfikatora URI kolekcji, ale wydaje się to sprzeczne z HTTP 1.1 RFC, co wydaje się sugerować, że dane wysyłane w żądaniu PUT powinny być interpretowane niezależnie z danych już obecnych w URI. Oznacza to, że klient musiałby wysłać za jednym razem pełny opis nowego stanu kolekcji, który może być znacznie większy niż zmiana, lub nawet być większy niż klient wiedziałby, kiedy złożyłby wniosek.

Oczywiście, byłbym szczęśliwy, gdyby odstąpić od RFC w razie potrzeby, ale wolałbym to zrobić w sposób konwencjonalny, jeśli taka konwencja istnieje.

Answer 1

Powinieneś użyć AtomPub. Został specjalnie zaprojektowany do zarządzania kolekcjami za pośrednictwem protokołu HTTP. Może istnieć nawet implementacja wybranego języka.

Answer 2

W przypadku POST przynajmniej wydaje się, że powinieneś mieć możliwość POST do URL-a listy, a treść żądania zawiera listę nowych zasobów zamiast pojedynczego nowego zasobu.

Answer 3

O ile rozumiem, REST oznacza Reprezentacyjny transfer państwowy, więc należy przenieść stan z klienta na serwer.

Jeśli oznacza to zbyt dużo danych, to być może trzeba zmienić swoją reprezentację. Struktura collectChange działałaby z serią usunięć (według identyfikatora) i dodatków (z osadzonymi pełnymi reprezentacjami xml), POSTed do adresu URL interfejsu obsługi. Implementacja interfejsu może wybrać własną metodę usuwania i uzupełnień po stronie serwera.

Najczystszą wersją będzie najprawdopodobniej określenie elementów według adresu URL, a kolekcja zawiera serię adresów URL. Nowa kolekcja może być PUT po zmianach wprowadzonych przez klienta, po której następuje seria PUT dodawanych elementów, a być może seria usunięć, jeśli chcesz rzeczywiście usunąć elementy z serwera, a nie tylko usunąć je z tej listy.

Answer 4

Można wprowadzić meta-reprezentacji istniejących elementów kolekcji, które nie potrzebują ich cały stan przeniesiony, więc w jakimś abstrakcyjnym kodem swoją zmiana mogłaby wyglądać następująco:

{existing elements 1-100} 
{new element foo with values "bar", "baz"} 
{existing element 105} 
{new element foobar with values "bar", "foo"} 
{existing elements 110-200}

Dodawanie (i modyfikujące) elementów jest poprzez zdefiniowanie ich wartości, usunięcie elementów odbywa się poprzez nie wspomnienie o tym, że nowa kolekcja i elementy zmiany kolejności są wykonywane poprzez określenie nowego zamówienia (jeśli zamówienie jest w ogóle przechowywane).

W ten sposób można łatwo przedstawić całą nową kolekcję bez konieczności ponownego przesyłania całej zawartości. Korzystanie z nagłówka If-Unmodified-Since zapewnia, że ​​twoje wyobrażenie o treści rzeczywiście odpowiada idei serwerów (tak, aby przypadkowo nie usunąć elementów, o których po prostu nie wiedziałeś, kiedy wniosek został złożony).

Answer 5

Być może zechcesz wymyślić zadanie zmiany jako zasób sam w sobie. Więc naprawdę chcesz wydać pojedynczy obiekt, który jest obiektem zbiorczej aktualizacji danych. Może ma nazwę, właściciela i duży obszar blobowy CSV, XML itp., Który musi zostać przeanalizowany i wykonany. W przypadku pliku CSV możesz również określić, jaki typ obiektów jest reprezentowany w danych CSV.

Wyświetlaj zadania, dodawaj zlecenie, przeglądaj status zlecenia, aktualizuj zlecenie (prawdopodobnie w celu jego uruchomienia/zatrzymania), usuń zlecenie (zatrzymaj je, jeśli działa) itd. Operacje te można łatwo mapować na Projekt interfejsu REST API.

Po zainstalowaniu tego można łatwo dodać różne typy danych, z którymi może poradzić sobie masowy aktualizator danych, a może nawet zmieszać je razem w tym samym zadaniu. Nie ma potrzeby powtarzania tego samego interfejsu API w całej aplikacji dla każdego rodzaju rzeczy, którą chcesz zaimportować.

To także bardzo łatwo nadaje się do realizacji zadania w tle. W takim przypadku prawdopodobnie chcesz dodać pola do poszczególnych obiektów zadań, które pozwalają klientowi API określić, w jaki sposób chcą być powiadamiani (adres URL, który chcą, abyś zrobił, gdy to zrobisz, lub wysłał im e-mail itp.) .

Answer 6

Tak, PUT tworzy/nadpisuje, ale nie aktualizuje częściowo.

Jeśli potrzebujesz częściowej semantyki aktualizacji, użyj PATCH. Zobacz http://greenbytes.de/tech/webdav/draft-dusseault-http-patch-14.html.