Czy rozsądne jest, aby zasoby REST były w liczbie pojedynczej i mnogiej?

10

Zastanawiam się, czy zamiast bardziej tradycyjnego układu takiego jak ten:

api/Products
GET // gets product(s) by id
PUT // updates product(s) by id
DELETE // deletes (product(s) by id
POST // creates product(s)

Czy bardziej przydatne byłoby użycie liczby pojedynczej i mnogiej, na przykład:

api/Product
GET // gets a product by id
PUT // updates a product by id
DELETE // deletes a product by id
POST // creates a product

api/Products
GET // gets a collection of products by id
PUT // updates a collection of products by id
DELETE // deletes a collection of products (not the products themselves)
POST // creates a collection of products based on filter parameters passed

Aby utworzyć kolekcję produktów, możesz:

POST api/Products {data: filters} // returns api/Products/<id>

A następnie, aby się do tego odwołać, możesz:

GET api/Products/<id> // returns array of products

Moim zdaniem główną zaletą robienia tego w ten sposób jest to, że pozwala na łatwe buforowanie kolekcji produktów. Można na przykład poświęcić godzinę życia na kolekcje produktów, co drastycznie zmniejsza połączenia na serwerze. Oczywiście obecnie widzę tylko dobrą stronę robienia rzeczy w ten sposób, co jest wadą?

Eva
źródło

Odpowiedzi:

6

Często, gdy kolekcja będzie najbardziej użytecznym sposobem interakcji z interfejsem API, łatwiej jest po prostu myśleć o pojedynczym jako kolekcji z tylko jednym członkiem. Następnie, jeśli później chcesz udostępnić API do interakcji z singlami, wystarczy jedynie pod przykryciem przekonwertować pojedynczy przekazany do kolekcji z tym elementem, a następnie używa identycznej implementacji innego API.

Wydaje mi się, że chcę powiedzieć, że jeśli chcesz, aby kolekcje były mechanizmem interakcji, zacznij od interfejsu API służącego tylko do gromadzenia, a po zakończeniu systemu drugi interfejs API jest prostym dodatkiem pomocniczym w warstwie interfejsu, który możesz dodać, jeśli uznasz to za szczególnie przydatne. Może się jednak okazać, że jego przydatność jest wystarczająco minimalna, aby zastosować YAGNI i po prostu użyć interfejsu kolekcji dla kilku żądanych pojedynczych egzemplarzy.

Jimmy Hoffa
źródło
Chociaż zgadzam się z twoim sentymentem, zakładając, że skorzystamy z powyższego przykładu, biorąc pod uwagę, że POST API / Produkty byłyby wykorzystywane do przekazywania parametrów filtru kolekcji, a nie danych do tworzenia nowych produktów, jaki byłby rozsądny sposób na utworzenie nowego produktu bez interfejsu / Produkt?
Eva,
@Evan Dlaczego nie można wysyłać do interfejsu API / Produkty wstawiać wielu (lub kolekcji jednego) Produktów? To wydaje mi się najbardziej logiczne. Być może opublikuj Produkty / Filtr do tworzenia filtrów lub uzyskaj, jeśli są to zadania pobierania, a nie kreacji.
Jimmy Hoffa
Dzięki za opracowanie, Jimmy. Powodem, dla którego nie widziałem tego w ten sposób, było rozważenie w powyższym przykładzie kolekcji jako zidentyfikowanego zasobu jako takiego. Na backendie api / Product może być „Product”, a api / Products, a więc „ProductCollection”. Jednak po zastanowieniu myślę, że może lepiej po prostu wyodrębnić, że wszystko z dala od API, jak w twojej sugestii ... teraz do prawdziwego pytania, czy odjechałeś od tego przystanku ciężarówki w drodze do Tajlandii, czy opuściłeś w bagażniku samochodu?
Eva,
@Evan Dam ci dwie wskazówki: mewy.
Jimmy Hoffa
1

Minusem jest to, że program wywołujący musi również pluralizować nazwę zasobu, co może być trudne dla tych języków klienta, które nie mają wbudowanych mechanizmów pluralizacji. Jeśli pozostawisz tę liczbę pojedynczą, osoba dzwoniąca może łatwiej zautomatyzować generowanie kodu dla swojej biblioteki klienta.

Jeśli chcesz to złagodzić, możesz samodzielnie wygenerować zestawy SDK dla swojej usługi REST. Lub możesz być po prostu uparty i zająć się skargą :)

Chris McCall
źródło