Dołącz/osadzić w porównaniu do łącza w RESTful APIs

Question

Tak więc ogólny wzorzec dla RESTful API polega na zwrocie pojedynczego obiektu z osadzonymi odsyłaczami, których można używać do pobierania powiązanych obiektów. Ale czasami dla wygody chcesz pobrać cały fragment wykresu obiektu naraz.

Na przykład, powiedzmy, że masz aplikację sklepu z klientów, zleceń i zwrotów. Aby wyświetlić dane osobowe, wszystkie rozkazy, a wszystkie zyski, razem, dla identyfikatora klienta 12345. (prawdopodobnie istnieje dobre powody, dla których nie zawsze powracający zamówień i zwrotów z klientem informacje osobiste.)

Czysto relaksującego sposób aby to zrobić jest coś jak:

1. GET /
   • zwraca listę szablonów łącza, w tym jeden do kwerendy dla klientów
2. GET /customers/12345 (w oparciu o łącza szablon z /)
   • wraca klient informacyjnych osobisty
   • zwroty linki, aby uzyskać zlecenia tego klienta i zwraca
3. GET /orders?customerId=12345 (od /customers/12345 odpowiedź)
   • dostaje rozkazy dla klienta 12345
4. GET /returns?customerId=12345 (od /customers/12345 odpowiedź)
   • dostaje zwrot dla klienta 12345

ale byłoby miło, gdy masz customers URI, aby móc pociągnąć to wszystko z powrotem w jednym zapytaniu . Czy istnieje najlepsza praktyka dla tego rodzaju zapytania dotyczącego wygody, w którym chcesz przekształcić niektóre lub wszystkie łącza zamiast tworzyć wiele żądań? Mam na myśli coś takiego:

GET /customers/12345?include=orders,returns 

Ale jeśli jest sposób, w jaki ludzie to robią, wolałbym nie tylko coś wymyślić.

(FWIW, ja nie buduje sklep, więc niech nie spierać o to, czy są one odpowiednie obiekty do modelu, lub jak masz zamiar drążyć rzeczywistych produktów, czy cokolwiek do.)

---

Updated dodać: wygląda na HAL speak te nazywane są „zasoby osadzone”, ale w przedstawionych przykładach, nie wydaje się być jakiś sposób na określenie, które zasoby osadzić.Znalazłem one blog post sugeruje coś takiego, co opisałem powyżej, stosując embed jako parametr zapytania:

GET /ticket/12?embed=customer.name,assigned_user 

Jest to standard lub pół-standardową praktyką, lub po prostu coś jeden bloger wykonane?

Answer 1

Ponieważ semantyka tych typów parametrów musiała być udokumentowana dla każdej relacji łącza, która je wspierała i że jest to mniej lub więcej coś, do kogo trzeba by kodować, nie wiem, że istnieje wszystko, co można zyskać dzięki standardowemu sposobowi wyrażania tego. Struktura adresu URL jest bardziej prawdopodobnie kierowana przez to, co jest najłatwiejsze lub najbardziej ostrożne, aby serwer powrócił, niż jakikolwiek konkretny standard lub najlepsza praktyka.

To powiedziawszy, jeśli szukasz inspiracji, możesz sprawdzić, co robi OData z $expand parameter i stworzyć z tego linka. Pamiętaj, że nadal powinieneś jasno zdefiniować kontrakt swojej relacji, w przeciwnym razie programiści klienta mogą zobaczyć konwencję podobną do OData i założyć (niesłusznie), że twoja aplikacja jest w pełni zgodna z OData i będzie zachowywać się jak jedna.